Přenos ACR pomocí Az CLI

ACR Transfer umožňuje přenášet obrazy kontejnerů a artefakty OCI mezi registry kontejnerů Azure pomocí zprostředkujícího účtu úložiště, což je ideální pro scénáře bez přístupu k síti a mezi různými cloudy. Přehled funkce najdete v tématu Přenos artefaktů do jiného registru.

Tento článek ukazuje, jak používat funkci ACR Transfer s rozšířením Az CLI acrtransfer.

Splnění předpokladů

Před pokusem o akce v tomto článku dokončete požadavky uvedené v požadavcích na ACR Transfer . To znamená, že:

• V obou cloudech máte existující registr skladové položky Premium.
• V obou cloudech máte existující kontejner účtu úložiště.
• Pokud používáte režim přístupu k úložišti tokenů SAS , ujistěte se, že máte existující službu Key Vault s tajným kódem obsahujícím platný token SAS s potřebnými oprávněními v obou cloudech.
• Pokud používáte režim přístupu k úložišti s spravovanou identitou, ujistěte se, že spravovaná identita datového toku má v účtu úložiště odpovídající roli RBAC (například Storage Blob Data Contributor).
• V obou cloudech máte nainstalovanou nejnovější verzi Az CLI.

ACR Transfer podporuje dva režimy přístupu k úložišti: token SAS a spravovaná identita. Musíte určit, který režim se má použít prostřednictvím parametru --storage-access-mode při vytváření kanálů. Podrobné porovnání najdete v tématu Režimy přístupu k úložišti.

Poznámka:

Parametr --storage-access-mode vyžaduje rozšíření acrtransfer Azure CLI verze 2.0.0 nebo novější. Pokud používáte starší verzi, upgradujte na az extension update --name acrtransferverzi .

Důležité

ACR Transfer podporuje artefakty s velikostmi vrstev až 8 GB kvůli technickým omezením.

Instalace rozšíření Az CLI

V AzureCloudu můžete rozšíření nainstalovat pomocí následujícího příkazu:

az extension add --name acrtransfer

Vytvoření ExportPipeline pomocí rozšíření Az CLI pro acrtransfer

Vytvořte prostředek ExportPipeline pro registr kontejnerů služby AzureCloud pomocí rozšíření acrtransfer pro Az CLI.

Režim tokenu SAS

Vytvořte kanál exportu s režimem přístupu k úložišti tokenů SAS, bez možností a identitou přiřazenou systémem:

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 \
--storage-access-mode SasToken

Vytvořte kanál exportu s režimem tokenu SAS, všemi možnými možnostmi a identitou přiřazenou uživatelem:

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 \
--storage-access-mode SasToken \
--options OverwriteBlobs ContinueOnErrors \
--assign-identity /subscriptions/$MySubID/resourceGroups/$MyRG/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$MyIdentity

Režim spravované identity

Když používáte režim přístupu k úložišti spravované identity, datový kanál se ověří přímo u účtu úložiště pomocí Entra spravované identity datového kanálu. Pro přístup k úložišti není vyžadován žádný token Key Vault ani token SAS.

Vytvořte kanál exportu s režimem spravované identity a identitou přiřazenou systémem:

az acr export-pipeline create \
--resource-group $MyRG \
--registry $MyReg \
--name $MyPipeline \
--storage-container-uri https://$MyStorage.blob.core.windows.net/$MyContainer \
--storage-access-mode ManagedIdentity

Vytvořte kanál exportu s režimem spravované identity, všemi možnými možnostmi a identitou přiřazenou uživatelem:

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

Důležité

Pokud používáte režim spravované identity, nezadáte--secret-uri parametr. Parametr --secret-uri se používá pouze s režimem tokenu SAS.

Možnosti exportu

options Vlastnost exportních kanálů podporuje volitelné logické hodnoty. Doporučuje se následující hodnoty:

Parametr	Hodnota
možnosti	OverwriteBlobs – Přepsat existující cílové bloby ContinueOnErrors – Pokud selže export jednoho artefaktu, pokračujte v exportu zbývajících artefaktů ve zdrojovém registru.

Dejte identitě ExportPipeline přístup k zásadám KeyVault.

Poznámka:

Tato část se vztahuje pouze při použití režimu přístupu k úložišti tokenů SAS . Pokud používáte režim přístupu k úložišti spravované identity, přeskočte tuto část a místo toho se ujistěte, že spravovaná identita vašeho datového proudu má v účtu úložiště příslušnou roli RBAC (například Storage Blob Data Contributor).

Pokud jste kanál vytvořili s identitou přiřazenou uživatelem, jednoduše udělte této identitě přiřazené uživatelem oprávnění zásad přístupu ke službě trezor klíčů.

Pokud jste potrubí vytvořili se systémově přiřazenou identitou, musíte nejprve načíst principalId, které systém přiřadil vašemu prostředku potrubí.

Spuštěním následujícího příkazu načtěte zdroj kanálu:

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

Z tohoto výstupu budete chtít zkopírovat hodnotu v principalId poli.

Potom spuštěním následujícího příkazu tomuto objektu zabezpečení udělíte příslušná secret get oprávnění zásad přístupu ke službě keyvault.

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

Vytvoření ImportPipeline pomocí rozšíření Az CLI acrtransfer

Vytvořte prostředek ImportPipeline v cílovém registru kontejneru pomocí rozšíření Az CLI s názvem acrtransfer. Ve výchozím nastavení je pipeline nastavená k automatickému vytvoření Import PipelineRun, když přidružený kontejner účtu úložiště obdrží nový artefaktový blob.

Režim tokenu SAS

Vytvořte kanál importu s režimem přístupu k úložišti tokenů SAS, bez možností a identitou přiřazenou systémem:

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 \
--storage-access-mode SasToken

Vytvořte kanál importu s režimem tokenu SAS, všemi možnými možnostmi, zakázaným triggerem zdroje a identitou přiřazenou uživatelem:

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 \
--storage-access-mode SasToken \
--options DeleteSourceBlobOnSuccess OverwriteTags ContinueOnErrors \
--assign-identity /subscriptions/$MySubID/resourceGroups/$MyRG/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$MyIdentity \
--source-trigger-enabled False

Režim spravované identity

Při použití režimu přístupu k úložišti Managed Identity se kanál přímo ověří v účtu úložiště pomocí Entra spravované identity kanálu. Pro přístup k úložišti není vyžadován žádný token Key Vault ani token SAS.

Vytvořte kanál importu s režimem spravované identity a identitou přiřazenou systémem:

az acr import-pipeline create \
--resource-group $MyRG \
--registry $MyReg \
--name $MyPipeline \
--storage-container-uri https://$MyStorage.blob.core.windows.net/$MyContainer \
--storage-access-mode ManagedIdentity

Vytvořte kanál importu s režimem spravované identity, všemi možnými možnostmi, zakázaným triggerem zdroje a identitou přiřazenou uživatelem:

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

Důležité

Pokud používáte režim spravované identity, nezadáte--secret-uri parametr. Parametr --secret-uri se používá pouze s režimem tokenu SAS.

Možnosti importu

options Vlastnost kanálu importu podporuje volitelné logické hodnoty. Doporučuje se následující hodnoty:

Parametr	Hodnota
možnosti	Přepsání značek – Přepsání existujících cílových značek DeleteSourceBlobOnSuccess – Odstranění objektu blob zdrojového úložiště po úspěšném importu do cílového registru ContinueOnErrors – Pokud selže import jednoho artefaktu, pokračujte v importu zbývajících artefaktů v cílovém registru.

Udělte identitě ImportPipeline přístup k zásadám KeyVault.

Poznámka:

Tato část se vztahuje pouze při použití režimu přístupu k úložišti tokenů SAS . Pokud používáte režim přístupu k úložišti spravované identity, přeskočte tuto část a místo toho se ujistěte, že spravovaná identita vaší pipeline má v účtu úložiště příslušnou roli RBAC (například Storage Blob Data Contributor).

Pokud jste kanál vytvořili s identitou přiřazenou uživatelem, jednoduše udělte této identitě přiřazené uživatelem oprávnění zásad přístupu ke službě trezor klíčů.

Pokud jste potrubí vytvořili se systémově přiřazenou identitou, musíte nejprve načíst principalId, které systém přiřadil vašemu prostředku potrubí.

Spuštěním následujícího příkazu načtěte zdroj kanálu:

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

Z tohoto výstupu budete chtít zkopírovat hodnotu v principalId poli.

Potom spustíte následující příkaz, který tomuto principálovi udělí odpovídající secret get zásady přístupu na vašem úložišti klíčů.

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

Vytvořte PipelineRun pro export pomocí rozšíření Az CLI acrtransfer

Vytvořte prostředek PipelineRun pro kontejnerový registr pomocí rozšíření acrtransfer pro Az CLI. Tento prostředek spustí prostředek ExportPipeline, který jste vytvořili dříve, a exportuje zadané artefakty z registru kontejneru jako objekt blob do kontejneru účtu úložiště.

Vytvořte export spuštění pipeliny:

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

Pokud znovu nasadíte prostředek PipelineRun se stejnými vlastnostmi, musíte použít příznak --force-redeploy.

Protokolování ověřování spuštění kanálu

Když se kanál spustí, CLI zobrazí zprávu protokolu označující, která metoda ověřování se používá pro přístup k účtu úložiště. To pomáhá ověřit, jestli potrubí používá Spravovanou identitu nebo autentizaci Tokenem SAS.

Authenticating to Storage Account using Entra Managed Identity.

nebo

Authenticating to Storage Account using Storage SAS Token.

Export artefaktů může trvat několik minut. Po úspěšném dokončení nasazení ověřte export artefaktu výpisem exportovaného objektu blob v kontejneru zdrojového účtu úložiště. Spusťte například příkaz az storage blob list :

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

Přenos objektu blob mezi doménou

Ve většině případů použití teď použijete řešení křížové domény nebo jinou metodu k přenosu objektu blob z účtu úložiště ve zdrojové doméně (účet úložiště přidružený k vašemu exportnímu kanálu) do účtu úložiště ve vaší cílové doméně (účet úložiště přidružený k vašemu importnímu kanálu). V tomto okamžiku předpokládáme, že objekt blob přišel do cílového účtu úložiště domény přidruženého k vašemu kanálu importu.

Aktivace prostředku ImportPipeline

Pokud jste při vytváření kanálu importu nepoužíli --source-trigger-enabled False parametr, kanál se aktivuje do 15 minut od doručení objektu blob do kontejneru účtu úložiště. Import artefaktů může trvat několik minut. Po úspěšném dokončení importu ověřte import artefaktů výpisem značek v úložišti, které importujete do cílového registru kontejneru. Například spusťte az acr repository show-tags:

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

Poznámka:

Trigger zdroje bude importovat pouze objekty blob, které mají čas poslední změny v posledních 60 dnech. Pokud chcete použít spouštěč zdroje k importu objektů blob starších než dané časové období, aktualizujte čas poslední změny objektů blob přidáním metadat k objektům blob nebo je naimportujte pomocí ručně vytvořených spuštění kanálu.

Pokud jste při vytváření importPipeline použili --source-trigger-enabled False parametr, budete muset ručně vytvořit PipelineRun, jak je znázorněno v následující části.

Vytvoření pipelineRunu pro import pomocí rozšíření Az CLI pro acrtransfer

Vytvořte prostředek PipelineRun pro kontejnerový registr pomocí rozšíření acrtransfer pro Az CLI. Tento zdroj spustí ImportPipeline, který jste vytvořili dříve, a importuje zadané blobové objekty z vašeho účtu úložiště do registru kontejnerů.

Vytvořte spuštění importního kanálu:

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

Pokud znovu nasadíte prostředek PipelineRun se stejnými vlastnostmi, musíte použít příznak --force-redeploy.

Import artefaktů může trvat několik minut. Po úspěšném dokončení importu ověřte import artefaktů výpisem úložišť v cílovém registru kontejneru. Například spusťte az acr repository show-tags:

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

Odstranění prostředků ACR Transfer

Smazat exportní kanál:

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

Odstranit ImportPipeline

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

Odstraňte prostředek PipelineRun Všimněte si, že tímto se akce provedená PipelineRunem nezvrátí. Toto je spíše jako mazání protokolu PipelineRun.

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

Řešení potíží s ACR Transferem

Pokyny k řešení potíží najdete v řešení potíží s přenosem ACR .

Další kroky

• Zjistěte, jak blokovat vytváření kanálů exportu z registru kontejnerů s omezeným přístupem k síti.