Panoramica della migrazione Prerequisiti Fase 1: Identifica i riferimenti esterni alle immagini Fase 2: Pianifica la struttura del repository Fase 3: Copiare le immagini su Amazon ECR Fase 4: Verifica dell'integrità dell'immagine Fase 5: Aggiornamento delle configurazioni di distribuzione Fase 6: Monitoraggio e convalida Considerazioni Approcci correlati

Migrazione delle immagini dei container da un registro di terze parti

Usa questa guida per eseguire una copia unica delle immagini dei container da un registro esterno nel tuo registro privato Amazon ECR in cui ECR Pull Through Cache non è supportato.

Se la fonte è un registro upstream supportato, non è necessario eseguire una copia una tantum. Vedi Sincronizzazione di un registro upstream con un registro privato Amazon ECR per configurare la memorizzazione automatica nella cache.

Nota

Amazon ECR memorizza la versione dell'immagine che hai copiato. Le versioni più recenti dal registro di origine non vengono estratte automaticamente. Per aggiornare un'immagine, invia la nuova versione al tuo repository Amazon ECR.

Panoramica della migrazione

La migrazione delle immagini dei container prevede i seguenti sei passaggi:

Identifica i riferimenti alle immagini esterne nei file di compilazione e distribuzione.
Pianifica la struttura del tuo repository Amazon ECR.
Copia le immagini su Amazon ECR.
Verifica l'integrità dell'immagine.
Aggiorna le configurazioni di distribuzione.
Monitora e convalida.

Prerequisiti

Prima di iniziare, verifica quanto segue:

Installa e configura la AWS CLI versione 2. Per ulteriori informazioni, consulta Installazione o aggiornamento della versione più recente della AWS CLI.
Installa Docker Engine o Docker Desktop versione 20.10 o successiva. Per ulteriori informazioni, consulta Installa Docker Engine nella documentazione di Docker.
(Facoltativo) Installskopeo, uno strumento open source per copiare le immagini dei contenitori tra registri senza un demone Docker locale. Per le istruzioni di installazione, consulta Skopeo su. GitHub
Verifica che la tua identità IAM disponga delle autorizzazioni per autenticarsi nel registro, creare repository e inviare immagini. Allega la policy AmazonEC2ContainerRegistryFullAccess gestita all'utente o al ruolo IAM che usi per eseguire questi comandi. Per ulteriori informazioni, consulta AWS politiche gestite per Amazon Elastic Container Registry.

Fase 1: Identifica i riferimenti esterni alle immagini

Cerca riferimenti a registri di terze parti nei file utilizzati per creare e distribuire immagini di container.

I comandi seguenti utilizzano la sintassi della shell Linux e macOS. Su Windows, usa Windows Subsystem for Linux (WSL) o Git Bash.

Identifica i riferimenti nei manifesti di distribuzione

Cerca le definizioni delle attività di Amazon ECS o i manifesti di Amazon EKS per riferimenti a immagini non ECR.

Per i manifesti di Kubernetes:


grep -rnH --include="*.yaml" --include="*.yml" "image:" . | grep -iv "dkr.ecr"

Per eseguire carichi di lavoro Amazon EKS:


kubectl get pods --all-namespaces -o jsonpath='{range .items[*]}{range .spec.containers[*]}{.image}{"\n"}{end}{range .spec.initContainers[*]}{.image}{"\n"}{end}{end}' | sort -u | grep -iv "dkr.ecr"

Per le definizioni delle attività di Amazon ECS:


aws ecs list-task-definitions --status ACTIVE --query 'taskDefinitionArns' --output text | \
  tr '\t' '\n' | \
  xargs -I {} aws ecs describe-task-definition --task-definition {} \
  --query 'taskDefinition.containerDefinitions[].image' --output text | \
  tr '\t' '\n' | sort -u | grep -iv "dkr.ecr"

Identifica i riferimenti in Dockerfiles

Per trovare le FROM direttive che fanno riferimento a registri esterni nelle directory di compilazione:


grep -rnH --include="Dockerfile*" "FROM" . | grep -iv "dkr.ecr"

L'output mostra file e numeri di riga che fanno riferimento a immagini esterne ad Amazon ECR. Ad esempio:

./app/Dockerfile:1:FROM python:3.11-slim
./service/Dockerfile:1:FROM nginx:1.25
./worker/Dockerfile:3:FROM redis:7-alpine

Identifica la frequenza di pull (opzionale)

Per capire con quale frequenza i carichi di lavoro provengono da registri di terze parti, consulta le analisi di utilizzo del registro upstream (ad esempio, Docker Hub fornisce i dati sulla frequenza di pull nella dashboard dell'account). L'elevata frequenza di pull aumenta il rischio di raggiungere i limiti di velocità. Per i limiti di velocità di Docker Hub, consulta la limitazione della velocità di Docker Hub nella documentazione di Docker.

Fase 2: Pianifica la struttura del repository

Prima di copiare le immagini, decidi come organizzarle in Amazon ECR.

Denominazione dei repository: Amazon ECR supporta i prefissi dello spazio dei nomi con barre. Usa i namespace per raggruppare immagini correlate per team, ambiente o applicazione. I namespace abilitano anche politiche IAM con ambito per prefisso. Ad esempio:


base-images/python
base-images/nginx
team-a/web-app
team-b/api-service

Immutabilità dei tag: per le immagini di produzione, abilita l'immutabilità dei tag per evitare che i tag delle immagini vengano sovrascritti. Per ulteriori informazioni, consulta Impedire la sovrascrittura dei tag di immagine in Amazon ECR.

Crittografia: scegli la configurazione di crittografia prima di creare repository. Non è possibile modificare la configurazione di crittografia dopo la creazione del repository. Per ulteriori informazioni, consulta Crittografia dei dati a riposo.

Costi di storage: Amazon ECR deduplica i livelli di immagine all'interno di ogni repository. Se più immagini condividono gli stessi livelli di base, ti verrà addebitato il costo di tali livelli solo una volta per repository. Tenete conto di questo fattore nelle stime dei costi quando pianificate le immagini da migrare.

Modelli di creazione di repository: se stai migrando molte immagini, configura un modello di creazione di repository per le azioni create-on-push con le tue impostazioni preferite (immutabilità dei tag, crittografia, politiche del ciclo di vita). Amazon ECR applica le impostazioni del modello quando crea repository per tuo conto durante il primo push. Per ulteriori informazioni, consulta Modelli per controllare i repository creati durante un pull through cache, la creazione in modalità push o un'azione di replica.

Firma gestita: se prevedi di firmare immagini con la firma gestita, configura le regole di firma prima di inviare le immagini. La firma avviene solo in fase push. Per ulteriori informazioni, consulta Firma le immagini in Amazon ECR.

Cross-Region replica: se i carichi di lavoro vengono eseguiti in più AWS regioni, configura le regole di replica prima di inviare le immagini. La replica copia solo le immagini inviate dopo la configurazione della regola. Per ulteriori informazioni, consulta Private image replication in Amazon ECR.

Nota

Multi-architecture le immagini (elenchi di manifesti) richiedono la copia di tutti i manifesti specifici della piattaforma oltre all'elenco dei manifesti. Se usi Docker, docker push i comandi docker pull and gestiscono solo la piattaforma che corrisponde all'architettura locale. Utilizzalo skopeo copy --all per copiare immagini multiarchitettura con tutte le piattaforme intatte.

Fase 3: Copiare le immagini su Amazon ECR

Prima di copiare le immagini, esegui l'autenticazione nel tuo registro privato Amazon ECR. L'URL del registro segue il formato. account-id.dkr.ecr.region.amazonaws.com Sostituiscilo 111122223333 con l'ID del tuo AWS account e us-east-1 con la tua regione negli esempi seguenti. Nella aws-cn partizione, il suffisso dell'URL del registro è. .amazonaws.com.cn In tutte le altre partizioni (aws,aws-us-gov), il suffisso è. .amazonaws.com

Per trovare l'ID del tuo account, esegui:


aws sts get-caller-identity --query Account --output text

Per ulteriori informazioni sui metodi di autenticazione, consultaAutenticazione del registro privato in Amazon ECR.

Se usi Docker (opzione A), esegui l'autenticazione con:


aws ecr get-login-password --region us-east-1 | \
docker login --username AWS --password-stdin 111122223333.dkr.ecr.us-east-1.amazonaws.com

Se usi skopeo (Opzione B), effettua invece l'autenticazione con. skopeo login Skopeo mantiene il proprio archivio di credenziali separato da Docker:


aws ecr get-login-password --region us-east-1 | \
skopeo login 111122223333.dkr.ecr.us-east-1.amazonaws.com --username AWS --password-stdin

Scegli uno dei seguenti metodi per copiare le tue immagini.

Opzione A: copia con Docker CLI

Usa questo metodo per un numero molto piccolo di immagini a piattaforma singola. Per una panoramica dettagliata del flusso di lavoro push, consulta. Spostamento di un'immagine durante il suo ciclo di vita in Amazon ECR

Crea il repository di destinazione (salta questo passaggio se il repository esiste già):


aws ecr create-repository \
  --repository-name base-images/nginx \
  --region us-east-1 \
  --image-tag-mutability IMMUTABLE \
  --encryption-configuration encryptionType=AES256

Se accedi da Docker Hub con un account autenticato per evitare i limiti di velocità, esegui prima. docker login docker.io Estrai l'immagine dal registro di terze parti:
```
docker pull nginx:1.25
```

Aggiungi un tag all'immagine per il tuo repository Amazon ECR:


docker tag nginx:1.25 111122223333.dkr.ecr.us-east-1.amazonaws.com/base-images/nginx:1.25

Invia l'immagine ad Amazon ECR:


docker push 111122223333.dkr.ecr.us-east-1.amazonaws.com/base-images/nginx:1.25

Per recuperare l'URI del repository dopo la creazione, esegui:


aws ecr describe-repositories --repository-names base-images/nginx --query 'repositories[0].repositoryUri' --output text

Nota

La CLI Docker copia solo la piattaforma che corrisponde al computer locale. Per copiare immagini con più architetture, usa l'opzione B con. skopeo

Opzione B: copia con skopeo (consigliata per la migrazione di massa)

Lo skopeo strumento copia le immagini direttamente tra i registri senza trasferirle sul computer locale. Questo approccio è più rapido per le operazioni di massa e supporta immagini multiarchitettura. Skopeo utilizza i prefissi di trasporto per identificare le posizioni delle immagini. Utilizzare per i registri remotidocker://.

Eseguite l'autenticazione nel registro di origine, se necessario. Ad esempio, per Docker Hub:
```
echo YOUR_TOKEN | skopeo login docker.io --username YOUR_USERNAME --password-stdin
```

Crea il repository di destinazione:


aws ecr create-repository \
  --repository-name base-images/nginx \
  --region us-east-1

Copia l'immagine (piattaforma singola):


skopeo copy docker://docker.io/library/nginx:1.25 \
  docker://111122223333.dkr.ecr.us-east-1.amazonaws.com/base-images/nginx:1.25

Per copiare un'immagine multiarchitettura con tutte le piattaforme, aggiungi il --all flag:


skopeo copy --all docker://docker.io/library/nginx:1.25 \
  docker://111122223333.dkr.ecr.us-east-1.amazonaws.com/base-images/nginx:1.25

Nota

skopeo copynon copia gli artefatti dei referenti OCI (firme, SBOM, attestazioni) associati a un'immagine. Se alle immagini di origine sono associati artefatti referrer, copiale separatamente o rifirma le immagini dopo la migrazione utilizzando la firma gestita.

Copia in blocco con uno script

Per migrare più immagini, crea un file di testo che elenchi le coppie di origine e destinazione, quindi usa uno script per copiarle.

Creare un file denominato images-to-migrate.txt:


docker.io/library/nginx:1.25 base-images/nginx:1.25
docker.io/library/python:3.11-slim base-images/python:3.11-slim
docker.io/library/redis:7-alpine base-images/redis:7-alpine
ghcr.io/org/custom-app:v2.1.0 team-a/custom-app:v2.1.0

Esegui lo script seguente:


#!/usr/bin/env bash
set -euo pipefail
ACCOUNT_ID="111122223333"
REGION="us-east-1"
REGISTRY="${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com"

aws ecr get-login-password --region ${REGION} | \
  skopeo login ${REGISTRY} --username AWS --password-stdin

while IFS=' ' read -r SOURCE DEST; do
  REPO_NAME=$(echo "${DEST}" | cut -d: -f1)

  # Create repository if it does not exist
  aws ecr create-repository \
    --repository-name "${REPO_NAME}" \
    --region "${REGION}" 2>/dev/null || true

  echo "Copying ${SOURCE} to ${REGISTRY}/${DEST}"
  skopeo copy --all "docker://${SOURCE}" "docker://${REGISTRY}/${DEST}"
done < images-to-migrate.txt

Nota

Amazon ECR applica i limiti di velocità delle API per le operazioni push. Per le migrazioni di grandi dimensioni, aggiungi la logica di riprova con backoff esponenziale in caso di limitazione. I token di autorizzazione scadono dopo 12 ore. Se la migrazione richiede più tempo, esegui nuovamente il comando di autenticazione prima di continuare.

Fase 4: Verifica dell'integrità dell'immagine

Dopo aver copiato le immagini, verifica che le immagini digest in Amazon ECR corrispondano alla fonte.

Ottieni il riassunto dell'immagine in Amazon ECR:
```
aws ecr describe-images \
  --repository-name base-images/nginx \
  --image-ids imageTag=1.25 \
  --query 'imageDetails[0].imageDigest' \
  --output text
```
Nota
Per le immagini a piattaforma singola, confronta direttamente i riassunti. Per le immagini multiarchitettura copiate con--all, in imageDigest Amazon ECR rappresenta l'elenco dei manifesti. Utilizza invece skopeo inspect --raw (mostrato di seguito) per confrontare i contenuti dell'elenco dei manifesti.
Confrontate il digest con il registro di origine. Utilizzare skopeo per ispezionare la fonte:
```
skopeo inspect docker://docker.io/library/nginx:1.25 | grep Digest
```
I digest devono corrispondere alle immagini a piattaforma singola copiate con. skopeo Se non corrispondono, la copia non è stata completata correttamente. Riprova l'operazione di copia. Se hai usato Docker (opzione A), il digest potrebbe essere diverso perché Docker può rielaborare i livelli durante il pull and push. Per una conservazione esatta del digest, usa. skopeo
Per le immagini con più architetture, aws ecr describe-images restituisce sia l'elenco dei manifesti che i manifesti delle singole piattaforme. Per confrontare direttamente il manifest list digest, usa sia skopeo inspect --raw sull'origine che sulla destinazione:
```
skopeo inspect --raw docker://111122223333.dkr.ecr.us-east-1.amazonaws.com/base-images/nginx:1.25
```
(Facoltativo) Eseguite una scansione delle immagini migrate per identificare le vulnerabilità. Per ulteriori informazioni, consulta Scansiona le immagini per individuare le vulnerabilità del software in Amazon ECR.

Fase 5: Aggiornamento delle configurazioni di distribuzione

Dopo aver verificato le immagini, aggiorna le configurazioni di distribuzione per estrarre da Amazon ECR e aggiorna le pipeline di CI/CD compilazione per inviare le immagini appena create a ECR. Ciò garantisce che le versioni future delle immagini siano disponibili senza copie manuali aggiuntive.

Definizione dei processi di Amazon ECS

Crea una nuova revisione della definizione dell'attività con l'URI dell'immagine aggiornato:


{
  "containerDefinitions": [
    {
      "name": "web",
      "image": "111122223333.dkr.ecr.us-east-1.amazonaws.com/base-images/nginx:1.25"
    }
  ]
}

Per ulteriori informazioni, consulta la sezione Aggiornamento di una definizione di attività nella Amazon ECS Developer Guide.

Manifesti Amazon EKS o Kubernetes

Aggiorna il image campo nelle specifiche del tuo pod:


spec:
  containers:
    - name: web
      image: 111122223333.dkr.ecr.us-east-1.amazonaws.com/base-images/nginx:1.25

Verifica che i tuoi nodi possano autenticarsi su Amazon ECR. I nodi Amazon EKS utilizzano l'helper di credenziali Amazon ECR per impostazione predefinita se la policy AmazonEC2ContainerRegistryReadOnly gestita è collegata al ruolo IAM del nodo.

File Docker

Aggiorna le FROM direttive nei tuoi Dockerfile:


FROM 111122223333.dkr.ecr.us-east-1.amazonaws.com/base-images/python:3.11-slim

Fase 6: Monitoraggio e convalida

Dopo aver ridistribuito i carichi di lavoro, verifica che tutte le immagini recuperate provengano ora da Amazon ECR.

Controlla i parametri per i tuoi repository CloudWatch . La RepositoryPullCount metrica conferma che si stanno verificando delle fluttuazioni. Per ulteriori informazioni, consulta Parametri del repository Amazon ECR.
Esamina BatchGetImage gli GetDownloadUrlForLayer eventi CloudTrail per confermare che i tuoi carichi di lavoro provengono dai repository previsti.
(Facoltativo) Configura le politiche del ciclo di vita per automatizzare la pulizia delle vecchie versioni delle immagini. Per ulteriori informazioni, consulta .

Considerazioni

Registri upstream non supportati: Pull Through Cache supporta un set specifico di registri upstream. Per i registri non presenti in quell'elenco (come JFrog Artifactory, Harbor o Sonatype Nexus), usa la CLI Docker o copia direttamente le immagini. skopeo
Large-scale o trasferimenti tra partizioni: per le migrazioni tra AWS partizioni (ad esempio verso) o i trasferimenti che coinvolgono migliaia di immagini, aws consulta la Guida per Data Transfer Hub on. aws-cnAWS
Lambda - Lambda richiede che le immagini dei container risiedano in Amazon ECR e non possono essere recuperate direttamente da registri di terze parti. Usa l'opzione A o l'opzione B per copiare le immagini in ECR prima di configurare la funzione Lambda.

Pull Through Cache: se il registro di origine è uno dei registri upstream supportati e desideri che Amazon ECR estragga e memorizzi automaticamente le immagini nella cache anziché eseguirne una copia una tantum, consulta. Sincronizzazione di un registro upstream con un registro privato Amazon ECR

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Spostamento di un'immagine durante il suo ciclo di vita

Ottimizzazione delle prestazioni