Sincronizzazione con registri di container di terze parti Considerazioni generali per le immagini dei container Amazon ECR Aggiungi input di attività a un'immagine Amazon ECR Utilizzo di Java nelle immagini dei container Amazon ECR Aggiungi input di attività a un'immagine Amazon ECR

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.

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

Argomenti

Sincronizzazione con registri di container di terze parti
Considerazioni generali per le immagini dei container Amazon ECR
Variabili di ambiente per i flussi HealthOmics di lavoro
Utilizzo di Java nelle immagini dei container Amazon ECR
Aggiungi input di attività a un'immagine del contenitore Amazon ECR

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 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
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:

Evita di dover migrare manualmente le immagini dei container su Amazon ECR o sincronizzare gli aggiornamenti dal repository di terze parti.
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.
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.

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.

Attività di configurazione

Crea una regola pull through cache
Autorizzazioni di registro per il registro upstream
Modelli per la creazione di repository
Creazione del flusso di lavoro

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 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:

Apri la console Amazon ECR: https://console.aws.amazon.com /ecr
Dal menu a sinistra, in Registro privato, espandi Caratteristiche e impostazioni, quindi scegli Pull through cache.
Dalla pagina Pull through cache, scegli Aggiungi regola.
Nel pannello del registro Upstream, scegli il registro upstream da sincronizzare con il registro privato, quindi scegli Avanti.
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).
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.
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.
Scegli Next (Successivo).
Rivedi la configurazione e scegli Crea per creare la regola.

Per ulteriori informazioni, consulta Creare una regola pull through cache (AWS Management 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.

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

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

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

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

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

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

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) 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 <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.

Dalla console Amazon ECR, apri il menu a sinistra, in Registro privato, espandi le autorizzazioni del registro, quindi scegli Genera dichiarazione.

In alto a destra, scegli JSON. Inserisci una politica simile alla seguente:

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 nella Amazon Elastic Container Registry User Guide.

Come creare un modello per la creazione di un repository:

Dalla console Amazon ECR, apri il menu a sinistra, in Registro privato, espandi Caratteristiche e impostazioni, quindi scegli Modelli di creazione di repository.
Scegli Crea modello.
Nei dettagli del modello, scegli Pull through cache.
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.
Scegli Next (Successivo).

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:

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.
Scegli Next (Successivo).
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, consultare Creare un flusso di lavoro privato.

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 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 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

Architettura

HealthOmics supporta contenitori x86_64. Se il computer locale è basato su ARM, come Apple Mac, usa un comando come il seguente per creare un'immagine del contenitore x86_64:
```
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

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_REGION: Questa variabile è la regione in cui è in esecuzione il contenitore.
AWS_WORKFLOW_ESEGUI: Questa variabile è il nome dell'esecuzione corrente.
AWS_WORKFLOW_RUN_ID: Questa variabile è l'identificatore di esecuzione della corsa corrente.
AWS_WORKFLOW_RUN_UUID: Questa variabile è l'UUID di esecuzione dell'esecuzione corrente.
AWS_WORKFLOW_ATTIVITÀ: Questa variabile è il nome dell'attività corrente.
AWS_WORKFLOW_TASK_ID: Questa variabile è l'identificatore dell'attività corrente.
AWS_WORKFLOW_TASK_UUID: 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 la dimensione massima dell'immagine del contenitore HealthOmics supportata.

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

File modello di parametri

Opzionale: licenze Sentieon