Illumina DRAGEN su HealthOmics flussi di lavoro privati

Illumina DRAGEN La versione 4.6 include una modalità software (modalità SW) che viene eseguita su istanze di CPU x86 standard e produce risultati corrispondenti FPGA-based DRAGEN. Puoi correre DRAGEN La modalità SW come attività in a HealthOmics flusso di lavoro privato in tutte le regioni in cui HealthOmics è disponibile. DRAGEN La modalità SW non utilizza istanze FPGA e non si specifica un acceleratore di attività.

Nota

DRAGEN è un software di terze parti concesso in licenza da Illumina. HealthOmics non fornisce DRAGEN licenze.

Come funziona Illumina DRAGEN HealthOmics

Ciascuna DRAGEN task convalida la sua licenza con Illumina quando l'attività inizia. La convalida della licenza richiede l'accesso a Internet in uscita. Per impostazione predefinita, HealthOmics esegue l'uso RESTRICTED modalità di rete, che consente l'accesso solo ad Amazon S3 e Amazon ECR nella stessa regione e blocca la rete Internet pubblica. Per eseguire DRAGEN, cominci tu a correre VPC modalità di rete con un VPC che indirizza il traffico in uscita attraverso un gateway NAT. Una corsa che utilizza RESTRICTED la modalità non può convalidare la licenza e il DRAGEN operazione non riuscita. DRAGEN La modalità SW viene eseguita su istanze di CPU x86, disponibile in tutte le regioni in cui HealthOmics supporta flussi di lavoro privati.

Per vedere quali DRAGEN le pipeline sono supportate in DRAGEN modalità SW, vedi le ultime Illumina DRAGEN note di rilascio.

Prerequisiti

• A DRAGEN licenza da Illumina.

• Un repository Amazon ECR privato nella regione in cui esegui il flusso di lavoro.

• Un VPC con sottoreti private, un gateway NAT e un gruppo di sicurezza che consente l'HTTPS in uscita (porta 443). Per un esempio di configurazione del VPC, consulta la HealthOmics Configurazione VPC sul GitHub.

• UN HealthOmics ruolo di servizio con accesso al tuo repository Amazon ECR e alle tue posizioni di input e output di Amazon S3. Consulta Ruoli di servizio per AWS HealthOmics.

Ottieni una licenza DRAGEN

Abbonati a DRAGEN attraverso Illumina. Dopo esserti iscritto, Illumina fornisce le credenziali che DRAGEN contenitore utilizza per convalidare la licenza.

Crea l'immagine del contenitore DRAGEN e inviala ad Amazon ECR

HealthOmics esegue le immagini dei container da repository privati di Amazon ECR nella stessa regione del flusso di lavoro. È necessario creare il DRAGEN immagine prima di inserirla nel tuo repository. HealthOmics supporti x86_64 contenitori. Per le istruzioni di installazione, consultare la DRAGEN riferimento alla modalità software.

Scarica il DRAGEN modalità SW RPM per DRAGEN 4.6.2 o successivo da Illumina. Ad esempio, il pacchetto per la versione 4.6.2 è dragen-softwaremode-4.6.2-4.6.2-1.el9.x86_64.rpm.

Prima di creare l'immagine, estrai DRAGEN installatore (.run file) senza eseguirlo e ispeziona gli RPM che contiene:

sh dragen-4.6.2-*.multi.el9.x86_64.run --noexec --keep --target ./extracted
ls ./extracted            # RPMs, flavors/, installer/, wrapper

Installa solo i pacchetti necessari per la modalità SW e salta il driver FPGA, i servizi host e i pacchetti bitstream:

Installa	Salta (e perché)
dragen-paths	dragen_drv Driver del kernel FPGA XDMA (un contenitore non può caricare i moduli del kernel)
dragen-host	dragen-host-services (no systemd in un'attività)
dragen	dragen-bitstream-* (non utilizzato in modalità SW)
dragen-platform-aws	Nessuno

File Dockerfile di esempio:

FROM oraclelinux:9
ARG DRAGEN_VERSION=4.6.2

# dnf resolves the RPM's declared deps (bzip2-libs, procps-ng, libgomp, ...)
COPY dragen-softwaremode-${DRAGEN_VERSION}-${DRAGEN_VERSION}-1.el9.x86_64.rpm /tmp/
RUN dnf -y install /tmp/dragen-softwaremode-*.rpm unzip \
    && rm -f /tmp/*.rpm \
    && dnf clean all && rm -rf /var/cache/dnf

# AWS CLI v2, used by tasks that fetch the API key from Secrets Manager
RUN curl -sSL "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o /tmp/awscli.zip \
    && unzip -q /tmp/awscli.zip -d /tmp && /tmp/aws/install && rm -rf /tmp/aws /tmp/awscli.zip

ENV PATH="/opt/dragen/${DRAGEN_VERSION}/bin:${PATH}"
CMD ["dragen", "--version"]

HealthOmics richiede linux/amd64 immagini. Costruire l'immagine con --platform flag ti consente di effettuare la compilazione incrociata da una macchina Apple Silicon.

docker build --platform linux/amd64 -t dragen:4.6.2-sw .

Crea un repository privato Amazon ECR, quindi invia il tuo DRAGEN L'immagine Docker nel tuo repository privato Amazon ECR. Per ulteriori informazioni, consulta Trasferimento di un'immagine Docker in un repository privato Amazon ECR nel Guida per l'utente di Amazon ECR.

Aggiungi una politica di repository in modo che HealthOmics può estrarre l'immagine del contenitore.

{
  "Version": "2012-10-17",
  "Statement": [{
    "Sid": "OmicsAccess",
    "Effect": "Allow",
    "Principal": { "Service": "omics.amazonaws.com" },
    "Action": ["ecr:BatchGetImage","ecr:GetDownloadUrlForLayer","ecr:BatchCheckLayerAvailability"]
  }]
}

Aggiungi il file che contiene tutte le dichiarazioni politiche.

aws ecr set-repository-policy --repository-name repository-name --region us-east-2 \
  --policy-text file://ecr-omics-policy.json

Per saperne di più HealthOmics requisiti, vedi Immagini contenitore per flussi di lavoro privati.

Configura la rete VPC per la convalida delle licenze

Crea le risorse di rete e un HealthOmics risorsa di configurazione, come descritto in Connessione HealthOmics dei flussi di lavoro a un VPC. Le tue corse devono usare VPC modalità di rete con un attivo HealthOmics configurazione che soddisfa i seguenti requisiti:

Impostazione	Requisito
Sottoreti	sottoreti private, una per zona di disponibilità, nelle zone di disponibilità dove HealthOmics opera.
Routing	Percorso 0.0.0.0/0 dalle sottoreti private a un gateway NAT, in modo che il compito raggiunga license.dragen.illumina.com.
Gruppo di sicurezza	Consenti TCP 443 in uscita. Per limitare la regola a destinazioni specifiche, usa Illumina endpoint di licenza.

Verifica che la tua configurazione soddisfi i requisiti di cui sopra:

aws omics get-configuration --name my-vpc-config --region us-east-2

È possibile riutilizzare la configurazione per tutti DRAGEN viene eseguito nella Regione.

Gestione delle chiavi di licenza

Puoi conservare una copia della tua chiave di licenza in AWS Secrets Manager. Perché HealthOmics non inserisce segreti nell'ambiente dell'attività, l'attività stessa deve chiamare Secrets Manager in fase di esecuzione per recuperare la chiave prima dell'esecuzione dragen.

Memorizza la chiave come segreta:

aws secretsmanager create-secret \
  --name dragen/illumina-api-key \
  --secret-string file://illumina-api-key.txt \
  --region us-east-2

Concedi al tuo ruolo di servizio il permesso di leggere il segreto (vedi Ruolo di esecuzione del servizio IAM), quindi recupera la chiave all'interno dell'attività prima di richiamarla dragen. Il DRAGEN l'immagine del contenitore deve includere AWS CLI (o un AWS SDK) per effettuare la chiamata.

Ad esempio, aggiungi quanto segue al blocco di comandi di un'attività, prima di dragen chiamata. Crea un file di testo semplice denominato illumina-api-key.txt nel /tmp/ elenco. Pass /tmp/illumina-api-key.txt a --api-key-file.

# Fetch the API key at runtime; never echo it.
KEY_FILE=/tmp/illumina-api-key.txt
REGION=$(echo "~{api_key_secret_arn}" | cut -d: -f4)
(umask 077; aws secretsmanager get-secret-value \
  --secret-id "~{api_key_secret_arn}" --region "${REGION}" \
  --query SecretString --output text > "${KEY_FILE}")

Perché l'attività è già in esecuzione VPC modalità di rete per raggiungere Illumina server di licenza, la stessa route del gateway NAT fornisce l'accesso all'endpoint API Secrets Manager. Per evitare di instradare questa chiamata attraverso il gateway NAT, aggiungete invece un endpoint di interfaccia VPC per Secrets Manager.

Puoi anche impostare la chiave di licenza come SSE-encrypted Amazon S3 crea un oggetto e specifica la chiave nei file di input per il flusso di lavoro o le attività del flusso di lavoro. Ciò garantisce che la chiave non appaia mai nella definizione del flusso di lavoro o in Amazon CloudWatch.

Inserimento di file Amazon S3:

aws s3 cp illumina-api-key.txt \
  s3://amzn-s3-demo-bucket/secrets/illumina-api-key.txt \
  --sse AES256 --region us-east-2

Concedi il HealthOmics ruolo di servizio, accesso in lettura a quell'oggetto (vedi Ruolo di esecuzione del servizio IAM), quindi fai riferimento ad esso come parametro del flusso di lavoro:

{
  "api_key_file": "s3://amzn-s3-demo-bucket/secrets/illumina-api-key.txt"
}

Assicuratevi che Illumina La chiave API negli input del flusso di lavoro ha l'ambito di DRAGEN solo attività.

Definire l'attività DRAGEN

Il seguente esempio WDL mostra la struttura di un campione DRAGEN operazione. È possibile passare la chiave di licenza come parte dei parametri di input del flusso di lavoro, come file JSON o valori in linea. È inoltre necessario passare l'URI dell'immagine come input del flusso di lavoro in modo che HealthOmics può verificare l'accesso prima dell'inizio dell'esecuzione. Per ulteriori informazioni, consulta HealthOmics eseguire ingressi.

Il dragen il processo a riga di comando e i valori delle risorse dipendono dall'analisi effettuata. Per eseguire il processo sono necessari almeno 16 vCPU e 128 GiB di memoria. Illumina consiglia fino a 64 vCPU e 256 GiB di memoria per alcune attività. Per ulteriori informazioni, consulta Risorse delle attività in un HealthOmics definizione del flusso di lavoro.

DRAGEN l'analisi è I/O intensiva e la velocità effettiva del disco può limitare le prestazioni, influendo sul tempo di esecuzione totale. Illumina consiglia volumi di storage temporanei locali per prestazioni ottimali. È possibile richiedere un aumento dello spazio di archiviazione temporaneo per attività utilizzando disks direttiva (o equivalente) nella definizione del flusso di lavoro. Consulta Configurazione delle dimensioni di archiviazione temporanee.

Vedi il IlluminaDRAGEN Guida per l'utente v4.6 per ulteriori informazioni sulle risorse richieste.

Esempio di attività DRAGEN (WDL)

version 1.0

workflow DragenSwGermline {
    input {
        String dragen_container
        File? hashtable_tar             # reuse an existing hash table; built from ref_fasta when absent
        File? ref_fasta
        File fastq_1
        File fastq_2
        String sample_id
        String api_key_secret_arn       # Secrets Manager ARN; the key itself never becomes a WDL value
        Boolean metering_preview = true # validate the API key without analysis or billing
    }

    call CheckLicenseSecret {
        input:
            secret_arn = api_key_secret_arn,
            dragen_container = dragen_container
    }

    if (!defined(hashtable_tar)) {
        call BuildHashTable {
            input:
                ref_fasta = select_first([ref_fasta]),
                dragen_container = dragen_container
        }
    }

    call DragenGermline {
        input:
            hashtable_tar = select_first([hashtable_tar, BuildHashTable.hashtable]),
            fastq_1 = fastq_1,
            fastq_2 = fastq_2,
            sample_id = sample_id,
            api_key_secret_arn = CheckLicenseSecret.checked_secret_arn,
            metering_preview = metering_preview,
            dragen_container = dragen_container
    }

    output {
        File? hashtable = BuildHashTable.hashtable
        Array[File] dragen_outputs = DragenGermline.outputs
        File dragen_log = DragenGermline.log
    }
}

# Fails fast if the run role can't read the secret or it's empty. Outputs only the ARN.
task CheckLicenseSecret {
    meta {
        volatile: true  # re-check access on every run
    }

    input {
        String secret_arn
        String dragen_container
    }

    command <<<
        set -euo pipefail
        REGION=$(echo "~{secret_arn}" | cut -d: -f4)
        KEY=$(aws secretsmanager get-secret-value \
            --secret-id "~{secret_arn}" --region "${REGION}" \
            --query SecretString --output text)
        if [ -z "${KEY}" ] || [ "${KEY}" = "None" ]; then
            echo "Secret has no SecretString; store it with --secret-string" >&2
            exit 1
        fi
        echo "API key secret is readable (${#KEY} characters)"
    >>>

    runtime {
        container: dragen_container
        cpu: 1
        memory: "2 GiB"
    }

    output {
        String checked_secret_arn = secret_arn
    }
}

# No license check, so this task is safe to call-cache.
task BuildHashTable {
    input {
        File ref_fasta
        String dragen_container
    }

    command <<<
        set -euo pipefail
        mkdir -p hashtable
        dragen --sw-mode --build-hash-table true \
            --ht-reference "~{ref_fasta}" \
            --ht-alt-liftover /opt/dragen/4.6.2/resources/ht_builder/hg38/bwa-kit_hs38DH_liftover.sam \
            --ht-num-threads 16 \
            --output-directory hashtable
        tar -cf hashtable.tar -C hashtable .
    >>>

    runtime {
        container: dragen_container
        cpu: 16
        memory: "128 GiB"
        disks: "200 GiB"
    }

    output {
        File hashtable = "hashtable.tar"
    }
}

task DragenGermline {
    meta {
        volatile: true  # contacts the license server; never reuse cached results
    }

    input {
        File hashtable_tar
        File fastq_1
        File fastq_2
        String sample_id
        String api_key_secret_arn
        Boolean metering_preview
        String dragen_container
    }

    command <<<
        set -euo pipefail
        mkdir -p output /tmp/reference /tmp/dragen-intermediate

        # Fetch the API key at runtime; never echo it.
        KEY_FILE=/tmp/illumina-api-key.txt
        REGION=$(echo "~{api_key_secret_arn}" | cut -d: -f4)
        (umask 077; aws secretsmanager get-secret-value \
            --secret-id "~{api_key_secret_arn}" --region "${REGION}" \
            --query SecretString --output text > "${KEY_FILE}")

        tar -xf "~{hashtable_tar}" -C /tmp/reference

        set +e
        dragen --sw-mode \
            --api-key-file "${KEY_FILE}" \
            -r /tmp/reference \
            -1 "~{fastq_1}" -2 "~{fastq_2}" \
            --RGID "~{sample_id}-rg" --RGSM "~{sample_id}" \
            --enable-map-align true --enable-map-align-output true \
            --enable-variant-caller true \
            --validate-pangenome-reference false \
            --intermediate-results-dir /tmp/dragen-intermediate \
            --output-directory output --output-file-prefix "~{sample_id}" \
            ~{if metering_preview then "--metering-preview" else ""} \
            2>&1 | tee dragen.log
        RC=${PIPESTATUS[0]}
        set -e
        rm -f "${KEY_FILE}"
        [ "${RC}" -eq 0 ] || { echo "DRAGEN failed (${RC})" >&2; exit "${RC}"; }
        touch output/.keep  # metering preview writes no outputs
    >>>

    runtime {
        container: dragen_container
        cpu: 16
        memory: "128 GiB"
        disks: "300 GiB"
    }

    output {
        Array[File] outputs = glob("output/*")
        File log = "dragen.log"
    }
}

Crea il tuo flusso di lavoro

Segui i passaggi indicati Crea un flusso di lavoro privato utilizzando la console, AWS CLI comandi o uno dei AWS SDK.

aws omics create-workflow --name dragen-sw-germline \
  --definition-zip fileb://workflow.zip --engine WDL --main main.wdl ...

Puoi usare HealthOmics linter per miniwdl o Nextflow per risolvere tutti gli errori prima della distribuzione.

Ruolo di esecuzione del servizio IAM

Crea un ruolo dedicato con privilegi minimi. Per ulteriori istruzioni dettagliate, consulta Autorizzazioni IAM per HealthOmics.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "S3",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::amzn-s3-demo-bucket",
        "arn:aws:s3:::amzn-s3-demo-bucket/*"
      ]
    },
    {
      "Sid": "Logs",
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:PutLogEvents",
        "logs:DescribeLogStreams"
      ],
      "Resource": "arn:aws:logs:us-east-2:123456789012:log-group:/aws/omics/*"
    },
    {
      "Sid": "ECRPull",
      "Effect": "Allow",
      "Action": [
        "ecr:BatchCheckLayerAvailability",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage"
      ],
      "Resource": "arn:aws:ecr:us-east-2:123456789012:repository/dragen"
    },
    {
      "Sid": "ECRAuth",
      "Effect": "Allow",
      "Action": "ecr:GetAuthorizationToken",
      "Resource": "*"
    }
  ]
}

Se utilizzi AWS Secrets Manager, hai bisogno dell'autorizzazione per leggere il segreto.

{
  "Sid": "ReadDragenApiKeySecret",
  "Effect": "Allow",
  "Action": "secretsmanager:GetSecretValue",
  "Resource": "arn:aws:secretsmanager:us-east-2:123456789012:secret:secret-name-*"
}

Inizia la corsa con una rete VPC

Inizia un run in VPC modalità di rete con la configurazione applicata e scratch-storage-mode impostato su LOCAL per reindirizzare scratch I/O sul disco locale.

aws omics start-run \
  --configuration-name my-vpc-config \
  --name dragen-sw-germline-run \
  --networking-mode VPC \
  --output-uri s3://amzn-s3-demo-bucket/runs/ \
  --parameters file://parameters.json \
  --region us-east-2 \
  --role-arn arn:aws:iam::123456789012:role/dragen-sw-omics-role \
  --scratch-storage-mode LOCAL \
  --storage-type DYNAMIC \
  --workflow-id workflow-id

Per ulteriori informazioni sull'impostazione del tipo di archiviazione in esecuzione, consulta Esegui tipi di storage nei flussi HealthOmics di lavoro.

Considerazioni

Disco locale

Ti consigliamo di eseguire DRAGEN con disco locale veloce sul nodo di calcolo. È possibile abilitare lo storage temporaneo scratch montato su /tmp impostando scratchStorageMode a LOCAL. Per ulteriori informazioni, consulta Archiviazione temporanea per le attività del flusso di lavoro HealthOmics.

Connessione Internet pubblica

DRAGEN convalida la licenza su Internet, ma è l'impostazione predefinita HealthOmics RESTRICTED la modalità di rete blocca le chiamate in uscita verso la rete Internet pubblica. Per correre DRAGEN, inizia la corsa con VPC la modalità di rete è abilitata e forniscono una configurazione con sottoreti che indirizzano il traffico in uscita attraverso un gateway NAT da raggiungere license.dragen.illumina.com tramite HTTPS. Per ulteriori informazioni, consulta Accesso a Internet per i VPC-connected flussi di lavoro.

Memorizzazione nella cache delle chiamate

Se si utilizza la memorizzazione nella cache delle chiamate, è necessario escludere le attività che richiedono controlli di licenza. La convalida della licenza contatta un servizio esterno e una cache di esecuzione potrebbe influire sugli output delle attività. È possibile escludere un'attività dalla memorizzazione nella cache utilizzando una direttiva nella definizione del flusso di lavoro. Per istruzioni su come escludere un'attività dalla memorizzazione nella cache delle chiamate, vedi Engine-specific funzionalità di memorizzazione nella cache.

Risoluzione dei problemi

Caratteristiche	Causa probabile	Azione
L'attività non riesce all'avvio a causa di un errore di licenza o di connessione in Amazon CloudWatch Registro dei log	L'esecuzione è iniziata nel RESTRICTED modalità	Inizia la corsa con --networking-mode VPC e un nome di configurazione.
Stesso errore in VPC modalità	La sottorete privata non ha alcun percorso verso un gateway NAT o il gruppo di sicurezza blocca la porta 443	Controlla la tabella delle rotte e il gruppo di sicurezza. Esegui il test di connettività in Test della connettività VPC.
Licenza rifiutata	Versione di prova scaduta, esaurita iCredits, o credenziali errate	Controlla lo stato del tuo abbonamento con Illumina.
AccessDenied tirando l'immagine	La policy relativa al ruolo del servizio o al repository non dispone delle autorizzazioni Amazon ECR	Consulta Autorizzazioni Amazon ECR.
La fase di licenza fallisce immediatamente con HTTP 403	Usato --lic-server (credenziali precedenti) invece di --api-key-file	Passa a --api-key-file (o --lic-credentials). --lic-server non è supportato in modalità SW.
L'operazione non riesce prima di qualsiasi controllo della licenza, anche con input minimi o di test	DRAGEN richiede un hard floor di 16 vCPU e oltre 120 GiB di memoria solo per convalidare la riga di comando	Usa almeno omics.r.4xlarge (16 vCPU, 128 GiB) per qualsiasi DRAGEN Attività in modalità SW, incluse le esecuzioni a secco.

Argomenti correlati

• Connessione HealthOmics dei flussi di lavoro a un VPC

• Accesso a Internet per i VPC-connected flussi di lavoro

• Immagini contenitore per flussi di lavoro privati

• Connessione HealthOmics viene eseguito su un server di licenze Sentienon