Imágenes de contenedores para flujos de trabajo privados - AWS HealthOmics
Sincronización con registros de contenedores de tercerosConsideraciones generales sobre las imágenes de contenedores de Amazon ECRAñadir entradas de tareas a una imagen de Amazon ECRUso de Java en imágenes de contenedores de Amazon ECRAñadir entradas de tareas a una imagen de Amazon ECR

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Imágenes de contenedores para flujos de trabajo privados

HealthOmics admite imágenes de contenedores alojadas en repositorios privados de Amazon ECR. Puede crear imágenes de contenedores y subirlas al repositorio privado. También puede utilizar su registro privado de Amazon ECR como caché extraíble para sincronizar el contenido de los registros anteriores.

Su repositorio de Amazon ECR debe residir en la misma AWS región que la cuenta que llama al servicio. La imagen del contenedor Cuenta de AWS puede ser propiedad de otra persona, siempre que el repositorio de imágenes de origen proporcione los permisos adecuados. Para obtener más información, consulte Políticas de acceso multicuenta a Amazon ECR.

Le recomendamos que defina la imagen del contenedor de Amazon ECR URIs como parámetros de su flujo de trabajo para poder verificar el acceso antes de que comience la ejecución. También facilita la ejecución de un flujo de trabajo en una nueva región al cambiar el parámetro de región.

nota

HealthOmics no admite contenedores ARM ni admite el acceso a repositorios públicos.

Para obtener información sobre la configuración de los permisos de IAM para acceder HealthOmics a Amazon ECR, consulte. HealthOmics Permisos de recursos

Sincronización con registros de contenedores de terceros

Puede utilizar las reglas de caché de extracción de Amazon ECR para sincronizar los repositorios de un registro ascendente compatible con sus repositorios privados de Amazon ECR. Para obtener más información, consulte Sincronizar un registro ascendente en la Guía del usuario de Amazon ECR.

La memoria caché extraíble crea automáticamente el repositorio de imágenes en su registro privado al crear la memoria caché y se sincroniza automáticamente con la imagen almacenada en caché cuando se producen cambios en la imagen original.

HealthOmics admite la caché extraíble para los siguientes registros ascendentes:

  • Amazon ECR Public

  • Registro de imágenes de contenedores de Kubernetes

  • Quay

  • Docker Hub

  • Para Microsoft Azure Container Registry

  • GitHub Registro de contenedores

  • GitLab Registro de contenedores

HealthOmics no admite la extracción de caché para un repositorio privado upstream de Amazon ECR.

Entre las ventajas de utilizar la memoria caché de extracción de Amazon ECR se incluyen las siguientes:

  1. Evita tener que migrar manualmente las imágenes del contenedor a Amazon ECR o sincronizar las actualizaciones del repositorio de terceros.

  2. Los flujos de trabajo acceden a las imágenes de contenedores sincronizadas de su repositorio privado, lo que resulta más fiable que descargar contenido en tiempo de ejecución desde un registro público.

  3. Como las cachés de extracción de Amazon ECR utilizan una estructura de URI predecible, el HealthOmics servicio puede mapear automáticamente el URI privado de Amazon ECR con el URI del registro anterior. No es necesario que actualice ni sustituya los valores de URI en la definición del flujo de trabajo.

Configurar la caché de extracción

Amazon ECR proporciona un registro para usted Cuenta de AWS en cada región. Asegúrese de crear la configuración de Amazon ECR en la misma región en la que planea ejecutar el flujo de trabajo.

En las siguientes secciones se describen las tareas de configuración de la memoria caché extraíble.

Cree una regla de extracción de caché

Cree una regla de caché de extracción de Amazon ECR para cada registro ascendente que contenga imágenes que desee almacenar en caché. Una regla especifica un mapeo entre un registro ascendente y el repositorio privado de Amazon ECR.

En el caso de un registro previo que requiera autenticación, debe proporcionar sus credenciales mediante AWS Secrets Manager.

nota

No modifique una regla de extracción de caché mientras una ejecución activa utilice el repositorio privado. La ejecución podría fallar o, lo que es más grave, provocar que tu canalización utilice imágenes inesperadas.

Para obtener más información, consulte Creación de una regla de extracción de caché en la Guía del usuario de Amazon Elastic Container Registry.

Cree una regla de extracción de caché mediante la consola

Para configurar la memoria caché de extracción, siga estos pasos con la consola Amazon ECR:

  1. Abra la consola de Amazon ECR: https://console.aws.amazon.com /ecr

  2. En el menú de la izquierda, en Registro privado, expanda Características y configuración y, a continuación, seleccione Extraer caché.

  3. En la página de extracción de caché, selecciona Añadir regla.

  4. En el panel de registro inicial, selecciona el registro inicial para sincronizarlo con tu registro privado y, a continuación, selecciona Siguiente.

  5. Si el registro principal requiere autenticación, la consola abre una nueva página en la que puede especificar el secreto de SageMaker IA que contiene sus credenciales. Elija Siguiente.

  6. En Especificar espacios de nombres, en el panel de espacios de nombres de Cache, elige si quieres crear los repositorios privados con un prefijo de repositorio específico o sin prefijo. Si opta por usar un prefijo, especifique el nombre del prefijo en el prefijo del repositorio de caché.

  7. En el panel del espacio de nombres de Upstream, elija si desea extraer datos de los repositorios ascendentes con un prefijo de repositorio específico o sin prefijo. Si opta por utilizar un prefijo, especifique el nombre del prefijo en el prefijo del repositorio de Upstream.

    El panel de ejemplos del espacio de nombres muestra un ejemplo de solicitud de cambios, una URL anterior y la URL del repositorio de caché que se ha creado.

  8. Elija Siguiente.

  9. Revisa la configuración y selecciona Crear para crear la regla.

Para obtener más información, consulte Crear una regla de extracción de memoria caché (consola AWS de administración).

Cree una regla de extracción de caché mediante la CLI

Utilice el create-pull-through-cache-rule comando Amazon ECR para crear una regla de extracción de caché. En el caso de los registros anteriores que requieren autenticación, almacene las credenciales en un secreto de Secrets Manager.

En las siguientes secciones se proporcionan ejemplos de cada registro ascendente compatible.

En el siguiente ejemplo se crea una regla de caché de extracción para el registro público de Amazon ECR. Especifica un prefijo de repositorio ecr-public, lo que da como resultado que cada repositorio se cree mediante la regla de caché de extracción para tener el esquema de nomenclatura de 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

En el siguiente ejemplo se crea una regla de extracción de caché para el registro público de Kubernetes. Especifica un prefijo de repositorio kubernetes, lo que da como resultado que cada repositorio se cree mediante la regla de caché de extracción para tener el esquema de nomenclatura de 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

El siguiente ejemplo crea una regla de extracción de caché para el registro público de Quay. Especifica un prefijo de repositorio quay, lo que da como resultado que cada repositorio se cree mediante la regla de caché de extracción para tener el esquema de nomenclatura de quay/upstream-repository-name.

aws ecr create-pull-through-cache-rule \
     --ecr-repository-prefix quay \
     --upstream-registry-url quay.io \
     --region us-east-1

El siguiente ejemplo crea una regla de caché de extracción para el registro de Docker Hub. Especifica un prefijo de repositorio docker-hub, lo que da como resultado que cada repositorio se cree mediante la regla de caché de extracción para tener el esquema de nomenclatura de docker-hub/upstream-repository-name. Debe especificar el nombre de recurso de Amazon (ARN) completo del secreto que contiene las credenciales de 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

En el siguiente ejemplo, se crea una regla de extracción de caché para el GitHub Container Registry. Especifica un prefijo de repositorio github, lo que da como resultado que cada repositorio se cree mediante la regla de caché de extracción para tener el esquema de nomenclatura de github/upstream-repository-name. Debe especificar el nombre de recurso de Amazon (ARN) completo del secreto que contiene sus credenciales de 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

El siguiente ejemplo crea una regla de caché de extracción para el Microsoft Azure Container Registry. Especifica un prefijo de repositorio azure, lo que da como resultado que cada repositorio se cree mediante la regla de caché de extracción para tener el esquema de nomenclatura de azure/upstream-repository-name. Debe especificar el nombre de recurso de Amazon (ARN) completo del secreto que contiene las credenciales de 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

En el siguiente ejemplo, se crea una regla de extracción de caché para el GitLab Container Registry. Especifica un prefijo de repositorio gitlab, lo que da como resultado que cada repositorio se cree mediante la regla de caché de extracción para tener el esquema de nomenclatura de gitlab/upstream-repository-name. Debe especificar el nombre de recurso de Amazon (ARN) completo del secreto que contiene sus credenciales de 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

Para obtener más información, consulte Crear una regla de extracción de caché (CLI) en la Guía del usuario de Amazon ECR.

Puede usar el comando get-run-task CLI para recuperar información sobre la imagen del contenedor utilizada para una tarea específica:

 aws omics get-run-task --id 1234567 --task-id <task_id>

El resultado incluye la siguiente información sobre la imagen del contenedor:

 "imageDetails": {
    "image": "string",
    "imageDigest": "string",
    "sourceImage": "string", 
          ...
 }

Permisos de registro para el registro inicial

Utilice los permisos de registro HealthOmics para poder utilizar la caché de extracción y extraer las imágenes del contenedor al registro privado de Amazon ECR. Añada una política de registro de Amazon ECR al registro que proporcione los contenedores utilizados en las ejecuciones.

La siguiente política otorga permiso al HealthOmics servicio para crear repositorios con los prefijos de caché de extracción especificados e iniciar extracciones ascendentes en estos repositorios.

  1. En la consola Amazon ECR, abra el menú de la izquierda, en Registro privado, expanda Permisos de registro y, a continuación, seleccione Generar declaración.

  2. En la parte superior derecha, selecciona JSON. Introduce una política similar a la siguiente:

    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/*"
            ] 
        }
    ]
}

Plantillas de creación de repositorios

Para utilizar el almacenamiento en caché mediante extracción HealthOmics, el repositorio de Amazon ECR debe tener una plantilla de creación de repositorios. La plantilla define los ajustes de configuración para cuando usted o Amazon ECR creen un repositorio privado para un registro principal.

Cada plantilla contiene un prefijo de espacio de nombres de repositorio, que Amazon ECR utiliza para hacer coincidir los nuevos repositorios con una plantilla específica. Las plantillas especifican la configuración de todos los ajustes del repositorio, incluidas las políticas de acceso basadas en los recursos, la inmutabilidad de las etiquetas, el cifrado y las políticas de ciclo de vida.

Para obtener más información, consulte las plantillas de creación de repositorios en la Guía del usuario de Amazon Elastic Container Registry.

Cómo crear una plantilla de creación de repositorios:

  1. En la consola Amazon ECR, abra el menú de la izquierda, en Registro privado, expanda Características y configuración y, a continuación, seleccione Plantillas de creación de repositorios.

  2. Seleccione Crear plantilla.

  3. En Detalles de la plantilla, selecciona Extraer caché.

  4. Elige si quieres aplicar esta plantilla a un prefijo específico o a todos los repositorios que no coincidan con otra plantilla.

    Si eliges un prefijo específico, introduce el valor del prefijo del espacio de nombres en Prefix. Especificó este prefijo al crear la regla de PTC.

  5. Elija Siguiente.

  6. En la página Añadir configuración de creación de repositorios, introduzca los permisos del repositorio. Utilice uno de los ejemplos de declaraciones de política o introduzca uno similar al ejemplo siguiente:

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

  7. Si lo desea, puede añadir la configuración del repositorio, como la política del ciclo de vida y las etiquetas. Amazon ECR aplica estas reglas a todas las imágenes de contenedores creadas para la caché de extracción que utilizan el prefijo especificado.

  8. Elija Siguiente.

  9. Revise la configuración y seleccione Siguiente.

Creación de un flujo de trabajo

Al crear un nuevo flujo de trabajo o una nueva versión del flujo de trabajo, revise las asignaciones del registro y actualícelas si es necesario. Para obtener más información, consulte Crear un flujo de trabajo privado.

Asignaciones de registro

Defina las asignaciones de registro para mapear entre los prefijos de su registro privado de Amazon ECR y los nombres de registro anteriores.

Para obtener más información sobre las asignaciones de registro de Amazon ECR, consulte Creación de una regla de extracción de caché en Amazon ECR.

El siguiente ejemplo muestra las asignaciones de registro a Docker Hub, Quay y Amazon ECR Public.

{
    "registryMappings": [
        {
            "upstreamRegistryUrl": "registry-1.docker.io",
            "ecrRepositoryPrefix": "docker-hub"
        },
        {
            "upstreamRegistryUrl": "quay.io",
            "ecrRepositoryPrefix": "quay"
        },
        {
            "upstreamRegistryUrl": "public.ecr.aws",
            "ecrRepositoryPrefix": "ecr-public"
        }
    ]
}

Mapeos de imágenes

Defina las asignaciones de imágenes para mapearlas entre los nombres de las imágenes tal como se definen en sus flujos de trabajo privados de Amazon ECR y los nombres de las imágenes en el registro principal.

Puede utilizar las asignaciones de imágenes con registros que admitan la extracción de memoria caché. También puedes usar mapeos de imágenes con registros anteriores en los que no se HealthOmics admite la extracción de la memoria caché. Tienes que sincronizar manualmente el registro original con tu repositorio privado.

Para obtener más información sobre las asignaciones de imágenes de Amazon ECR, consulte Creación de una regla de extracción de caché en Amazon ECR.

El siguiente ejemplo muestra las asignaciones de imágenes privadas de Amazon ECR a una imagen genómica pública y a la imagen más reciente de 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",
        }
    ]
}

Consideraciones generales sobre las imágenes de contenedores de Amazon ECR

  • Arquitectura

    HealthOmics admite contenedores x86_64. Si su máquina local está basada en ARM, como Apple Mac, utilice un comando como el siguiente para crear una imagen de contenedor x86_64: 

    docker build --platform amd64 -t my_tool:latest .

  • Punto de entrada y carcasa

    HealthOmics Los motores de flujo de trabajo inyectan scripts bash como una sustitución de comandos en las imágenes del contenedor utilizadas en las tareas del flujo de trabajo. Por lo tanto, las imágenes de los contenedores deben crearse sin un PUNTO DE ENTRADA específico, de modo que el shell bash sea el predeterminado.

  • Rutas montadas

    Un sistema de archivos compartido se monta en las tareas del contenedor en /tmp. Se anularán todos los datos o herramientas integrados en la imagen del contenedor en esta ubicación.

    La definición del flujo de trabajo está disponible para las tareas mediante un montaje de solo lectura en /mnt/workflow.

  • Tamaño de imagen

    Consulte los tamaños máximos HealthOmics cuotas de tamaño fijo del flujo de trabajo de imagen del contenedor.

Variables de entorno para los HealthOmics flujos de trabajo

HealthOmics proporciona variables de entorno que contienen información sobre el flujo de trabajo que se ejecuta en el contenedor. Puede utilizar los valores de estas variables en la lógica de las tareas del flujo de trabajo.

Todas las variables HealthOmics del flujo de trabajo comienzan con el AWS_WORKFLOW_ prefijo. Este prefijo es un prefijo de variable de entorno protegido. No utilice este prefijo para sus propias variables en los contenedores de flujo de trabajo.

HealthOmics proporciona las siguientes variables de entorno de flujo de trabajo:

AWS_REGION

Esta variable es la región en la que se ejecuta el contenedor.

AWS_WORKFLOW_EJECUTAR

Esta variable es el nombre de la ejecución actual.

AWS_WORKFLOW_RUN_ID

Esta variable es el identificador de ejecución de la ejecución actual.

AWS_WORKFLOW_RUN_UUID

Esta variable es el UUID de ejecución de la ejecución actual.

AWS_WORKFLOW_TAREA

Esta variable es el nombre de la tarea actual.

AWS_WORKFLOW_TASK_ID

Esta variable es el identificador de la tarea actual.

AWS_WORKFLOW_TASK_UUID

Esta variable es el UUID de la tarea actual.

El siguiente ejemplo muestra los valores típicos de cada variable de entorno:

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

Uso de Java en imágenes de contenedores de Amazon ECR

Si una tarea de flujo de trabajo utiliza una aplicación Java como GATK, tenga en cuenta los siguientes requisitos de memoria para el contenedor:

  • Las aplicaciones Java utilizan memoria de pila y memoria de pila. De forma predeterminada, la memoria de pila máxima es un porcentaje de la memoria total disponible en el contenedor. Este valor predeterminado depende de la distribución específica de la JVM y de la versión de la JVM, así que consulte la documentación correspondiente a su JVM o establezca explícitamente el máximo de memoria de pila mediante las opciones de la línea de comandos de Java (como `-Xmx`).

  • No establezcas que la memoria de pila máxima sea el 100% de la asignación de memoria del contenedor, ya que la pila de JVM también requiere memoria. También se necesita memoria para el recolector de elementos no utilizados de la JVM y para cualquier otro proceso del sistema operativo que se ejecute en el contenedor.

  • Algunas aplicaciones Java, como GATK, pueden utilizar invocaciones de métodos nativos u otras optimizaciones, como los archivos de mapeo de memoria. Estas técnicas requieren asignaciones de memoria que se realicen «fuera del montón», que no están controladas por el parámetro de pila máxima de la JVM.

    Si sabe (o sospecha) que su aplicación Java asigna memoria fuera del montón, asegúrese de que la asignación de la memoria a las tareas incluya los requisitos de memoria fuera del montón.

    Si estas asignaciones fuera del montón provocan que el contenedor se quede sin memoria, normalmente no aparecerá ningún OutOfMemory error de Java, ya que la JVM no controla esta memoria.

Añadir entradas de tareas a una imagen de contenedor de Amazon ECR

Añada todos los ejecutables, bibliotecas y scripts necesarios para ejecutar una tarea de flujo de trabajo a la imagen de Amazon ECR que se utiliza para ejecutar la tarea.

Se recomienda evitar el uso de scripts, archivos binarios y bibliotecas externos a la imagen del contenedor de tareas. Esto es especialmente importante cuando se utilizan nf-core flujos de trabajo que utilizan un bin directorio como parte del paquete de flujo de trabajo. Si bien este directorio estará disponible para la tarea de flujo de trabajo, se monta como un directorio de solo lectura. Los recursos necesarios de este directorio deben copiarse en la imagen de la tarea y estar disponibles en tiempo de ejecución o al crear la imagen del contenedor utilizada para la tarea.

Consulte HealthOmics cuotas de tamaño fijo del flujo de trabajo el tamaño máximo de la imagen del contenedor que HealthOmics admite.