Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # Immagini di container per flussi di lavoro privati HealthOmics supporta immagini di container ospitate in repository privati di Amazon ECR. Puoi creare immagini di contenitori e caricarle nel repository privato. Puoi anche utilizzare il tuo registro privato Amazon ECR come cache pull through per sincronizzare il contenuto dei registri upstream. Il tuo repository Amazon ECR deve risiedere nella stessa AWS regione dell'account che chiama il servizio. L'immagine del contenitore Account AWS può essere di proprietà di un altro soggetto, a condizione che l'archivio delle immagini di origine fornisca le autorizzazioni appropriate. Per ulteriori informazioni, consulta [Politiche per l'accesso ad Amazon ECR su più account](permissions-ecr.md#permissions-cross-account). Ti consigliamo di definire l'immagine del contenitore Amazon ECR URIs come parametri del flusso di lavoro in modo che l'accesso possa essere verificato prima dell'inizio dell'esecuzione. Inoltre, semplifica l'esecuzione di un flusso di lavoro in una nuova regione modificando il parametro Region. **Nota** HealthOmics non supporta i contenitori ARM e non supporta l'accesso agli archivi pubblici. Per informazioni sulla configurazione delle autorizzazioni IAM per l'accesso HealthOmics ad Amazon ECR, consulta. [HealthOmics Autorizzazioni per le risorse](permissions-resource.md) **Topics** + [Sincronizzazione con registri di container di terze parti](#ecr-pull-through) + [Considerazioni generali per le immagini dei container Amazon ECR](#ecr-considerations) + [Variabili di ambiente per i flussi HealthOmics di lavoro](#ecr-env-vars) + [Utilizzo di Java nelle immagini dei container Amazon ECR](#ecr-java-considerations) + [Aggiungi input di attività a un'immagine del contenitore Amazon ECR](#ecr-tasks) ## Sincronizzazione con registri di container di terze parti Puoi utilizzare le regole pull through cache di Amazon ECR per sincronizzare i repository in un registro upstream supportato con i tuoi repository privati Amazon ECR. Per ulteriori informazioni, consulta [Sincronizzare un registro upstream](https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache.html) nella *Amazon ECR User Guide.* La cache pull through crea automaticamente l'archivio di immagini nel registro privato al momento della creazione della cache e si sincronizza automaticamente con l'immagine memorizzata nella cache in caso di modifiche all'immagine upstream. HealthOmics supporta la cache pull through per i seguenti registri upstream: + Amazon ECR Public + Registro delle immagini del contenitore Kubernetes + Quay + Docker Hub + Microsoft Azure Container Registry + GitHub Registro dei contenitori + GitLab Registro dei contenitori HealthOmics non supporta la cache pull through per un repository privato Amazon ECR upstream. I vantaggi dell'utilizzo della cache pull through di Amazon ECR includono: 1. Evita di dover migrare manualmente le immagini dei container su Amazon ECR o sincronizzare gli aggiornamenti dal repository di terze parti. 1. I flussi di lavoro accedono alle immagini sincronizzate dei contenitori nel tuo repository privato, che è più affidabile rispetto al download di contenuti in fase di esecuzione da un registro pubblico. 1. Poiché le cache pull through di Amazon ECR utilizzano una struttura URI prevedibile, il HealthOmics servizio può mappare automaticamente l'URI privato di Amazon ECR con l'URI del registro upstream. Non è necessario aggiornare e sostituire i valori URI nella definizione del flusso di lavoro. **Topics** + [Configurazione della cache pull through](#ecr-pull-through-configure) + [Mappature del registro](#ecr-pull-through-registry-mapping) + [Mappature delle immagini](#ecr-pull-through-mapping-format) ### Configurazione della cache pull through Amazon ECR fornisce un registro per ogni Account AWS regione. Assicurati di creare la configurazione Amazon ECR nella stessa regione in cui intendi eseguire il flusso di lavoro. Le seguenti sezioni descrivono le attività di configurazione per il pull through cache. **Topics** + [Crea una regola pull through cache](#create-ecr-ptc) + [Autorizzazioni di registro per il registro upstream](#reg-ecr-ptc) + [Modelli per la creazione di repository](#repo-create-templates-ptc) + [Creazione del flusso di lavoro](#reg-mapping-ecr-ptc) #### Crea una regola pull through cache Crea una regola pull through cache di Amazon ECR per ogni registro upstream contenente immagini che desideri memorizzare nella cache. Una regola specifica una mappatura tra un registro upstream e l'archivio privato Amazon ECR. Per un registro upstream che richiede l'autenticazione, fornisci le tue credenziali utilizzando AWS Secrets Manager. **Nota** Non modificare una regola di pull through cache mentre un'esecuzione attiva utilizza il repository privato. L'esecuzione potrebbe fallire o, cosa ancora più importante, far sì che la pipeline utilizzi immagini inaspettate. Per ulteriori informazioni, consulta [Creazione di una regola pull through cache](https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache-creating-rule.html) nella *Amazon Elastic Container Registry User Guide*. ##### Crea una regola pull through cache utilizzando la console Per configurare la cache pull through, segui questi passaggi utilizzando la console Amazon ECR: 1. Apri la console Amazon ECR: https://console.aws.amazon.com /ecr 1. Dal menu a sinistra, in **Registro privato**, espandi **Caratteristiche e impostazioni**, quindi scegli **Pull** through cache. 1. Dalla pagina **Pull through cache**, scegli **Aggiungi regola**. 1. **Nel pannello del **registro Upstream**, scegli il registro upstream da sincronizzare con il registro privato, quindi scegli Avanti.** 1. Se il registro upstream richiede l'autenticazione, la console apre una nuova pagina in cui specifichi il segreto SageMaker AI che contiene le tue credenziali. Scegli **Next (Successivo)**. 1. In **Specificate namespaces**, nel pannello **Cache namespace**, scegliete se creare i repository privati utilizzando un prefisso di repository specifico o senza prefisso. **Se scegliete di utilizzare un prefisso, specificate il nome del prefisso nel prefisso del repository Cache.** 1. Nel pannello dello spazio dei **nomi Upstream**, scegliete se estrarre dai repository upstream utilizzando un prefisso di repository specifico o senza prefisso. **Se scegliete di utilizzare un prefisso, specificate il nome del prefisso nel prefisso del repository Upstream.** Il pannello di esempio **Namespace mostra un esempio** di pull request, un URL upstream e l'URL del cache repository che viene creato. 1. Scegli **Next (Successivo)**. 1. Rivedi la configurazione e scegli **Crea per creare** la regola. Per ulteriori informazioni, consulta [Creare una regola pull through cache (AWS Management Console)](https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache-creating-rule.html#pull-through-cache-creating-rule-console). ##### Crea una regola pull through cache utilizzando la CLI Usa il **create-pull-through-cache-rule** comando Amazon ECR per creare una regola pull through cache. Per i registri upstream che richiedono l'autenticazione, memorizzate le credenziali in un segreto di Secrets Manager. Le sezioni seguenti forniscono esempi per ogni registro upstream supportato. ##### Per Amazon ECR Public L'esempio seguente crea una regola di cache pull-through per il registro pubblico di Amazon ECR. Specifica un prefisso di `ecr-public`, che fa sì che ciascun repository creato utilizzando la regola della cache pull-through abbia lo schema di denominazione di `ecr-public/upstream-repository-name`. ``` aws ecr create-pull-through-cache-rule \ --ecr-repository-prefix ecr-public \ --upstream-registry-url public.ecr.aws \ --region us-east-1 ``` ##### Per Kubernetes Container Registry L'esempio seguente crea una regola di cache pull through per il registro pubblico Kubernetes. Specifica un prefisso di `kubernetes`, che fa sì che ciascun repository creato utilizzando la regola della cache pull-through abbia lo schema di denominazione di `kubernetes/upstream-repository-name`. ``` aws ecr create-pull-through-cache-rule \ --ecr-repository-prefix kubernetes \ --upstream-registry-url registry.k8s.io \ --region us-east-1 ``` ##### Per Quay L'esempio seguente crea una regola di cache pull-through per il registro pubblico Quay. Specifica un prefisso di `quay`, che fa sì che ciascun repository creato utilizzando la regola della cache pull-through abbia lo schema di denominazione di `quay/upstream-repository-name`. ``` aws ecr create-pull-through-cache-rule \ --ecr-repository-prefix quay \ --upstream-registry-url quay.io \ --region us-east-1 ``` ##### Per Docker Hub L'esempio seguente crea una regola di cache pull-through per il registro Docker Hub. Specifica un prefisso di `docker-hub`, che fa sì che ciascun repository creato utilizzando la regola della cache pull-through abbia lo schema di denominazione di `docker-hub/upstream-repository-name`. Devi specificare nella sua interezza il nome della risorsa Amazon (ARN) del segreto contenente le credenziali di Docker Hub. ``` aws ecr create-pull-through-cache-rule \ --ecr-repository-prefix docker-hub \ --upstream-registry-url registry-1.docker.io \ --credential-arn arn:aws:secretsmanager:us-east-1:111122223333:secret:ecr-pullthroughcache/example1234 \ --region us-east-1 ``` ##### Per Container Registry GitHub L'esempio seguente crea una regola pull through cache per il GitHub Container Registry. Specifica un prefisso di `github`, che fa sì che ciascun repository creato utilizzando la regola della cache pull-through abbia lo schema di denominazione di `github/upstream-repository-name`. È necessario specificare l'Amazon Resource Name (ARN) completo del segreto contenente le credenziali del GitHub Container Registry. ``` aws ecr create-pull-through-cache-rule \ --ecr-repository-prefix github \ --upstream-registry-url ghcr.io \ --credential-arn arn:aws:secretsmanager:us-east-1:111122223333:secret:ecr-pullthroughcache/example1234 \ --region us-east-1 ``` ##### Per Microsoft Azure Container Registry L'esempio seguente crea una regola pull through cache per il Microsoft Azure Container Registry. Specifica un prefisso di `azure`, che fa sì che ciascun repository creato utilizzando la regola della cache pull-through abbia lo schema di denominazione di `azure/upstream-repository-name`. Devi specificare nella sua interezza il nome della risorsa Amazon (ARN) del segreto contenente le credenziali di Microsoft Azure Container Registry. ``` aws ecr create-pull-through-cache-rule \ --ecr-repository-prefix azure \ --upstream-registry-url myregistry.azurecr.io \ --credential-arn arn:aws:secretsmanager:us-east-1:111122223333:secret:ecr-pullthroughcache/example1234 \ --region us-east-1 ``` ##### Per GitLab Container Registry L'esempio seguente crea una regola pull through cache per il GitLab Container Registry. Specifica un prefisso di `gitlab`, che fa sì che ciascun repository creato utilizzando la regola della cache pull-through abbia lo schema di denominazione di `gitlab/upstream-repository-name`. È necessario specificare l'Amazon Resource Name (ARN) completo del segreto contenente le credenziali del GitLab Container Registry. ``` aws ecr create-pull-through-cache-rule \ --ecr-repository-prefix gitlab \ --upstream-registry-url registry.gitlab.com \ --credential-arn arn:aws:secretsmanager:us-east-1:111122223333:secret:ecr-pullthroughcache/example1234 \ --region us-east-1 ``` Per ulteriori informazioni, consulta [Create a pull through cache rule (CLI)](https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache-creating-rule.html#pull-through-cache-creating-rule-cli) nella *Amazon ECR* User Guide. È possibile utilizzare il comando **get-run-task** CLI per recuperare informazioni sull'immagine del contenitore utilizzata per un'attività specifica: ``` aws omics get-run-task --id 1234567 --task-id ``` L'output include le seguenti informazioni sull'immagine del contenitore: ``` "imageDetails": { "image": "string", "imageDigest": "string", "sourceImage": "string", ... } ``` #### Autorizzazioni di registro per il registro upstream Utilizza le autorizzazioni di registro HealthOmics per consentire l'utilizzo della cache pull through e per inserire le immagini del contenitore nel registro privato di Amazon ECR. Aggiungi una policy del registro Amazon ECR al registro che fornisce i contenitori utilizzati nelle esecuzioni. La seguente policy concede al HealthOmics servizio l'autorizzazione a creare repository con i prefissi pull through cache specificati e ad avviare recuperi upstream in questi repository. 1. Dalla console Amazon ECR, apri il menu a sinistra, in **Registro privato**, espandi **le autorizzazioni del registro**, quindi scegli **Genera** dichiarazione. 1. In alto a destra, scegli JSON. Inserisci una politica simile alla seguente: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowPTCinRegPermissions", "Effect": "Allow", "Principal": { "Service": "omics.amazonaws.com" }, "Action": [ "ecr:CreateRepository", "ecr:BatchImportUpstreamImage" ], "Resource": [ "arn:aws:ecr:us-east-1:123456789012:repository/ecr-public/*", "arn:aws:ecr:us-east-1:123456789012:repository/docker-hub/*" ] } ] } ``` ------ #### Modelli per la creazione di repository Per utilizzare il pull through caching in HealthOmics, il repository Amazon ECR deve disporre di un modello di creazione del repository. Il modello definisce le impostazioni di configurazione per quando tu o Amazon ECR create un repository privato per un registro upstream. Ogni modello contiene un prefisso dello spazio dei nomi del repository, che Amazon ECR utilizza per abbinare i nuovi repository a un modello specifico. I modelli specificano la configurazione per tutte le impostazioni del repository, comprese le politiche di accesso basate sulle risorse, l'immutabilità dei tag, la crittografia e le politiche del ciclo di vita. Per ulteriori informazioni, consulta [Modelli di creazione di repository](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-creation-templates.html) nella *Amazon Elastic Container Registry User Guide*. Come creare un modello per la creazione di un repository: 1. Dalla console Amazon ECR, apri il menu a sinistra, in **Registro privato**, espandi **Caratteristiche e impostazioni**, quindi scegli Modelli di **creazione di repository**. 1. Scegli **Crea modello**. 1. Nei **dettagli del modello**, scegli **Pull through cache**. 1. Scegli se applicare questo modello a un prefisso specifico o a tutti i repository che non corrispondono a un altro modello. **Se scegli **Un prefisso specifico, inserisci il valore del prefisso** dello spazio dei nomi in Prefisso.** Avete specificato questo prefisso quando avete creato la regola PTC. 1. Scegli **Next (Successivo)**. 1. **Nella pagina **Aggiungi configurazione per la creazione del repository**, immettete le autorizzazioni per la creazione del repository.** Utilizza una delle istruzioni politiche di esempio o inseriscine una simile all'esempio seguente: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "PTCRepoCreationTemplate", "Effect": "Allow", "Principal": { "Service": "omics.amazonaws.com" }, "Action": [ "ecr:BatchGetImage", "ecr:GetDownloadUrlForLayer" ], "Resource": "*" } ] } ``` ------ 1. Facoltativamente, puoi aggiungere impostazioni del repository come i criteri del ciclo di vita e i tag. Amazon ECR applica queste regole a tutte le immagini di container create per la cache pull through che utilizzano il prefisso specificato. 1. Scegli **Next (Successivo)**. 1. **Controlla la configurazione e scegli Avanti.** #### Creazione del flusso di lavoro Quando crei un nuovo flusso di lavoro o una nuova versione del flusso di lavoro, rivedi i mapping del registro e aggiornali se necessario. Per informazioni dettagliate, vedi [Creare un flusso di lavoro privato](create-private-workflow.md). ### Mappature del registro Definisci le mappature del registro da mappare tra i prefissi nel tuo registro Amazon ECR privato e i nomi del registro upstream. Per ulteriori informazioni sulle mappature del registro Amazon ECR, consulta [Creazione di una regola pull through cache in Amazon](https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache-creating-rule.html) ECR. L'esempio seguente mostra le mappature del registro su Docker Hub, Quay e Amazon ECR Public. ``` { "registryMappings": [ { "upstreamRegistryUrl": "registry-1.docker.io", "ecrRepositoryPrefix": "docker-hub" }, { "upstreamRegistryUrl": "quay.io", "ecrRepositoryPrefix": "quay" }, { "upstreamRegistryUrl": "public.ecr.aws", "ecrRepositoryPrefix": "ecr-public" } ] } ``` ### Mappature delle immagini Definisci le mappature delle immagini da mappare tra i nomi delle immagini definiti nei flussi di lavoro privati di Amazon ECR e i nomi delle immagini nel registro upstream. Puoi utilizzare le mappature delle immagini con registri che supportano la cache pull through. È inoltre possibile utilizzare le mappature delle immagini con registri upstream che non supportano il pull through cache. HealthOmics È necessario sincronizzare manualmente il registro upstream con il repository privato. Per ulteriori informazioni sulle mappature delle immagini di Amazon ECR, consulta [Creazione di una regola pull through cache in Amazon](https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache-creating-rule.html) ECR. L'esempio seguente mostra le mappature da immagini private di Amazon ECR a un'immagine genomica pubblica e all'ultima immagine di Ubuntu. ``` { "imageMappings": [ { "sourceImage": "public.ecr.aws/aws-genomics/broadinstitute/gatk:4.6.0.2", "destinationImage": "123456789012.dkr.ecr.us-east-1.amazonaws.com/broadinstitute/gatk:4.6.0.2" }, { "sourceImage": "ubuntu:latest", "destinationImage": "123456789012.dkr.ecr.us-east-1.amazonaws.com/custom/ubuntu:latest", } ] } ``` ## Considerazioni generali per le immagini dei container Amazon ECR + Architecture HealthOmics supporta contenitori x86\$164. Se il computer locale è basato su ARM, come Apple Mac, usa un comando come il seguente per creare un'immagine del contenitore x86\$164: ``` docker build --platform amd64 -t my_tool:latest . ``` + Entrypoint e shell HealthOmics i motori di workflow iniettano gli script di bash come comando che sostituiscono le immagini dei contenitori utilizzate dalle attività del flusso di lavoro. Pertanto, le immagini dei contenitori dovrebbero essere create senza un ENTRYPOINT specificato in modo tale che una shell bash sia l'impostazione predefinita. + Percorsi montati Un filesystem condiviso viene montato sulle attività del contenitore in /tmp. Tutti i dati o gli strumenti incorporati nell'immagine del contenitore in questa posizione verranno sovrascritti. La definizione del flusso di lavoro è disponibile per le attività tramite un montaggio in sola lettura in /mnt/workflow. + Dimensione dell’immagine Vedi per le dimensioni massime delle immagini dei contenitori. [HealthOmics quote a dimensione fissa per il flusso di lavoro](fixed-quotas.md#fixed-quotas-workflows) ## Variabili di ambiente per i flussi HealthOmics di lavoro HealthOmics fornisce variabili di ambiente che contengono informazioni sul flusso di lavoro in esecuzione nel contenitore. È possibile utilizzare i valori di queste variabili nella logica delle attività del flusso di lavoro. Tutte le variabili HealthOmics del flusso di lavoro iniziano con il `AWS_WORKFLOW_` prefisso. Questo prefisso è un prefisso di variabile di ambiente protetto. Non utilizzate questo prefisso per le vostre variabili nei contenitori del flusso di lavoro. HealthOmics fornisce le seguenti variabili di ambiente di flusso di lavoro: **AWS\$1REGION** Questa variabile è la regione in cui è in esecuzione il contenitore. **AWS\$1WORKFLOW\$1ESEGUI** Questa variabile è il nome dell'esecuzione corrente. **AWS\$1WORKFLOW\$1RUN\$1ID** Questa variabile è l'identificatore di esecuzione della corsa corrente. **AWS\$1WORKFLOW\$1RUN\$1UUID** Questa variabile è l'UUID di esecuzione dell'esecuzione corrente. **AWS\$1WORKFLOW\$1ATTIVITÀ** Questa variabile è il nome dell'attività corrente. **AWS\$1WORKFLOW\$1TASK\$1ID** Questa variabile è l'identificatore dell'attività corrente. **AWS\$1WORKFLOW\$1TASK\$1UUID** Questa variabile è l'UUID dell'attività corrente. L'esempio seguente mostra i valori tipici per ogni variabile di ambiente: ``` AWS Region: us-east-1 Workflow Run: arn:aws:omics:us-east-1:123456789012:run/6470304 Workflow Run ID: 6470304 Workflow Run UUID: f4d9ed47-192e-760e-f3a8-13afedbd4937 Workflow Task: arn:aws:omics:us-east-1:123456789012:task/4192063 Workflow Task ID: 4192063 Workflow Task UUID: f0c9ed49-652c-4a38-7646-60ad835e0a2e ``` ## Utilizzo di Java nelle immagini dei container Amazon ECR Se un'attività di workflow utilizza un'applicazione Java come GATK, considera i seguenti requisiti di memoria per il contenitore: + Le applicazioni Java utilizzano la memoria stack e la memoria heap. Per impostazione predefinita, la memoria heap massima è una percentuale della memoria totale disponibile nel contenitore. Questa impostazione predefinita dipende dalla distribuzione JVM specifica e dalla versione JVM, quindi consulta la documentazione pertinente per la tua JVM o imposta esplicitamente il massimo della memoria heap utilizzando le opzioni della riga di comando Java (come `-Xmx`). + Non impostate che la memoria heap massima sia pari al 100% dell'allocazione di memoria del contenitore, poiché anche lo stack JVM richiede memoria. La memoria è richiesta anche per il Garbage Collector JVM e per qualsiasi altro processo del sistema operativo in esecuzione nel contenitore. + Alcune applicazioni Java, come GATK, possono utilizzare invocazioni di metodi nativi o altre ottimizzazioni come i file di mappatura della memoria. Queste tecniche richiedono allocazioni di memoria eseguite «off heap», che non sono controllate dal parametro JVM maximum heap. Se sai (o sospetti) che la tua applicazione Java alloca memoria off-heap, assicurati che l'allocazione della memoria delle attività includa i requisiti di memoria off-heap. Se queste allocazioni off-heap causano l'esaurimento della memoria nel contenitore, in genere non viene visualizzato un **OutOfMemory** errore Java, perché la JVM non controlla questa memoria. ## Aggiungi input di attività a un'immagine del contenitore Amazon ECR Aggiungi tutti gli eseguibili, le librerie e gli script necessari per eseguire un'attività di workflow nell'immagine Amazon ECR utilizzata per eseguire l'attività. È consigliabile evitare l'uso di script, file binari e librerie esterni all'immagine del contenitore di attività. Ciò è particolarmente importante quando si utilizzano `nf-core` flussi di lavoro che utilizzano una `bin` directory come parte del pacchetto workflow. Sebbene questa directory sia disponibile per l'attività del flusso di lavoro, viene montata come directory di sola lettura. Le risorse richieste in questa directory devono essere copiate nell'immagine dell'attività e rese disponibili in fase di esecuzione o durante la creazione dell'immagine del contenitore utilizzata per l'attività. Vedi [HealthOmics quote a dimensione fissa per il flusso di lavoro](fixed-quotas.md#fixed-quotas-workflows) la dimensione massima dell'immagine del contenitore HealthOmics supportata.