Images de conteneur pour les flux de travail privés - AWS HealthOmics
Synchronisation avec des registres de conteneurs tiersConsidérations générales relatives aux images de conteneurs Amazon ECRAjouter des entrées de tâches à une image Amazon ECRUtilisation de Java dans les images de conteneurs Amazon ECRAjouter des entrées de tâches à une image Amazon ECR

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Images de conteneur pour les flux de travail privés

HealthOmics prend en charge les images de conteneurs hébergées dans les référentiels privés Amazon ECR. Vous pouvez créer des images de conteneur et les télécharger dans le référentiel privé. Vous pouvez également utiliser votre registre privé Amazon ECR sous forme de cache d'extraction pour synchroniser le contenu des registres en amont.

Votre référentiel Amazon ECR doit résider dans la même AWS région que le compte appelant le service. Une autre personne Compte AWS peut être propriétaire de l'image du conteneur, à condition que le référentiel d'images source fournisse les autorisations appropriées. Pour de plus amples informations, veuillez consulter Politiques relatives à l'accès multicompte à Amazon ECR.

Nous vous recommandons de définir votre image de conteneur Amazon ECR en URIs tant que paramètre de votre flux de travail afin que l'accès puisse être vérifié avant le début de l'exécution. Cela facilite également l'exécution d'un flux de travail dans une nouvelle région en modifiant le paramètre Région.

Note

HealthOmics ne prend pas en charge les conteneurs ARM et ne prend pas en charge l'accès aux référentiels publics.

Pour plus d'informations sur la configuration des autorisations IAM pour accéder HealthOmics à Amazon ECR, consultez. HealthOmics Autorisations relatives aux ressources

Synchronisation avec des registres de conteneurs tiers

Vous pouvez utiliser les règles de cache d'extraction d'Amazon ECR pour synchroniser les référentiels d'un registre en amont pris en charge avec vos référentiels privés Amazon ECR. Pour plus d'informations, consultez Synchroniser un registre en amont dans le guide de l'utilisateur Amazon ECR.

Le cache d'extraction crée automatiquement le référentiel d'images dans votre registre privé lorsque vous créez le cache, et il se synchronise automatiquement avec l'image mise en cache lorsque des modifications sont apportées à l'image en amont.

HealthOmics prend en charge le cache d'extraction pour les registres en amont suivants :

  • Amazon ECR Public

  • Registre d'images de conteneurs Kubernetes

  • Quay

  • Docker Hub

  • Microsoft Azure Container Registry

  • GitHub Registre des conteneurs

  • GitLab Registre des conteneurs

HealthOmics ne prend pas en charge le cache d'extraction pour un référentiel privé Amazon ECR en amont.

Les avantages de l'utilisation du cache d'extraction Amazon ECR sont les suivants :

  1. Vous évitez d'avoir à migrer manuellement les images de conteneur vers Amazon ECR ou à synchroniser les mises à jour depuis le référentiel tiers.

  2. Les flux de travail accèdent aux images de conteneur synchronisées de votre référentiel privé, ce qui est plus fiable que le téléchargement de contenu depuis un registre public au moment de l'exécution.

  3. Comme les caches d'extraction Amazon ECR utilisent une structure d'URI prévisible, le HealthOmics service peut automatiquement mapper l'URI privé Amazon ECR avec l'URI de registre en amont. Vous n'êtes pas obligé de mettre à jour et de remplacer les valeurs d'URI dans la définition du flux de travail.

Configuration du cache d'extraction

Amazon ECR fournit un registre pour vous Compte AWS dans chaque région. Assurez-vous de créer la configuration Amazon ECR dans la même région que celle où vous prévoyez d'exécuter le flux de travail.

Les sections suivantes décrivent les tâches de configuration du cache d'extraction.

Création d'une règle de cache d'extraction

Créez une règle de cache d'extraction Amazon ECR pour chaque registre en amont contenant des images que vous souhaitez mettre en cache. Une règle spécifie un mappage entre un registre en amont et le référentiel privé Amazon ECR.

Pour un registre en amont qui nécessite une authentification, vous devez fournir vos informations d'identification à l'aide d'AWS Secrets Manager.

Note

Ne modifiez pas une règle de cache d'extraction lorsqu'une exécution active utilise le référentiel privé. L'exécution pourrait échouer ou, plus grave encore, entraîner l'utilisation d'images inattendues dans votre pipeline.

Pour plus d'informations, consultez la section Création d'une règle de cache d'extraction dans le guide de l'utilisateur d'Amazon Elastic Container Registry.

Création d'une règle de cache d'extraction à l'aide de la console

Pour configurer le cache d'extraction, procédez comme suit à l'aide de la console Amazon ECR :

  1. Ouvrez la console Amazon ECR : https://console.aws.amazon.com /ecr

  2. Dans le menu de gauche, sous Registre privé, développez Fonctionnalités et paramètres, puis choisissez Pull through cache.

  3. Sur la page du cache d'extraction, choisissez Ajouter une règle.

  4. Dans le panneau de registre Upstream, choisissez le registre amont à synchroniser avec votre registre privé, puis choisissez Next.

  5. Si le registre en amont nécessite une authentification, la console ouvre une nouvelle page dans laquelle vous spécifiez le secret SageMaker AI qui contient vos informations d'identification. Choisissez Suivant.

  6. Sous Spécifier les espaces de noms, dans le panneau de l'espace de noms du cache, choisissez de créer les référentiels privés à l'aide d'un préfixe de référentiel spécifique ou sans préfixe. Si vous choisissez d'utiliser un préfixe, spécifiez le nom du préfixe dans le préfixe du référentiel de cache.

  7. Dans le panneau de l'espace de noms Upstream, choisissez si vous souhaitez extraire des référentiels en amont en utilisant un préfixe de référentiel spécifique ou sans préfixe. Si vous choisissez d'utiliser un préfixe, spécifiez le nom du préfixe dans le préfixe du référentiel Upstream.

    Le panneau d'exemple Namespace affiche un exemple de pull request, une URL en amont et l'URL du référentiel de cache créé.

  8. Choisissez Suivant.

  9. Vérifiez la configuration et choisissez Create pour créer la règle.

Pour plus d'informations, voir Création d'une règle de cache d'extraction (console AWS de gestion).

Création d'une règle de cache d'extraction à l'aide de la CLI

Utilisez la create-pull-through-cache-rule commande Amazon ECR pour créer une règle de cache d'extraction. Pour les registres en amont qui nécessitent une authentification, stockez les informations d'identification dans un secret Secrets Manager.

Les sections suivantes fournissent des exemples pour chaque registre en amont pris en charge.

L'exemple suivant crée une règle de mise en cache par extraction pour le registre public Amazon ECR. Il spécifie un préfixe de référentiel de ecr-public, ce qui fait que chaque référentiel créé à l'aide de la règle de mise en cache par extraction aura le schéma de dénomination 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

L'exemple suivant crée une règle de mise en cache par extraction pour le registre public Kubernetes. Il spécifie un préfixe de référentiel de kubernetes, ce qui fait que chaque référentiel créé à l'aide de la règle de mise en cache par extraction aura le schéma de dénomination 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

L'exemple suivant crée une règle de mise en cache par extraction pour le registre public Quay. Il spécifie un préfixe de référentiel de quay, ce qui fait que chaque référentiel créé à l'aide de la règle de mise en cache par extraction aura le schéma de dénomination 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

L'exemple suivant crée une règle de mise en cache par extraction pour le registre Docker Hub. Il spécifie un préfixe de référentiel de docker-hub, ce qui fait que chaque référentiel créé à l'aide de la règle de mise en cache par extraction aura le schéma de dénomination de docker-hub/upstream-repository-name. Vous devez spécifier l'Amazon Resource Name (ARN) complet du secret contenant vos informations d'identification 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'exemple suivant crée une règle de cache d'extraction pour le registre des GitHub conteneurs. Il spécifie un préfixe de référentiel de github, ce qui fait que chaque référentiel créé à l'aide de la règle de mise en cache par extraction aura le schéma de dénomination de github/upstream-repository-name. Vous devez spécifier le nom Amazon Resource Name (ARN) complet du secret contenant vos informations d'identification du registre des GitHub conteneurs.

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'exemple suivant crée une règle de cache d'extraction pour le Microsoft Azure Container Registry. Il spécifie un préfixe de référentiel de azure, ce qui fait que chaque référentiel créé à l'aide de la règle de mise en cache par extraction aura le schéma de dénomination de azure/upstream-repository-name. Vous devez spécifier l'Amazon Resource Name (ARN) complet du secret contenant vos informations d'identification 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'exemple suivant crée une règle de cache d'extraction pour le registre des GitLab conteneurs. Il spécifie un préfixe de référentiel de gitlab, ce qui fait que chaque référentiel créé à l'aide de la règle de mise en cache par extraction aura le schéma de dénomination de gitlab/upstream-repository-name. Vous devez spécifier le nom Amazon Resource Name (ARN) complet du secret contenant vos informations d'identification du registre des GitLab conteneurs.

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

Pour plus d'informations, consultez la section Créer une règle de cache d'extraction (CLI) dans le guide de l'utilisateur Amazon ECR.

Vous pouvez utiliser la commande get-run-task CLI pour récupérer des informations sur l'image du conteneur utilisée pour une tâche spécifique :

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

La sortie inclut les informations suivantes concernant l'image du conteneur :

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

Autorisations de registre pour le registre en amont

Utilisez les autorisations de registre HealthOmics pour autoriser l'utilisation du cache d'extraction et l'extraction des images du conteneur dans le registre privé Amazon ECR. Ajoutez une politique de registre Amazon ECR au registre qui fournit les conteneurs utilisés lors des exécutions.

La politique suivante autorise le HealthOmics service à créer des référentiels avec le ou les préfixes de cache d'extraction spécifiés et à lancer des extractions en amont dans ces référentiels.

  1. Depuis la console Amazon ECR, ouvrez le menu de gauche, sous Registre privé, développez les autorisations du registre, puis choisissez Generate statement.

  2. En haut à droite, choisissez JSON. Entrez une politique similaire à la suivante :

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

Modèles de création de référentiels

Pour utiliser la mise en cache par extraction HealthOmics, le référentiel Amazon ECR doit disposer d'un modèle de création de référentiel. Le modèle définit les paramètres de configuration lorsque vous ou Amazon ECR créez un référentiel privé pour un registre en amont.

Chaque modèle contient un préfixe d'espace de noms de référentiel, qu'Amazon ECR utilise pour associer les nouveaux référentiels à un modèle spécifique. Les modèles spécifient la configuration de tous les paramètres du référentiel, notamment les politiques d'accès basées sur les ressources, l'immuabilité des balises, le chiffrement et les politiques de cycle de vie.

Pour plus d'informations, consultez les modèles de création de référentiels dans le guide de l'utilisateur d'Amazon Elastic Container Registry.

Comment créer un modèle de création de référentiel :

  1. Depuis la console Amazon ECR, ouvrez le menu de gauche, sous Registre privé, développez Fonctionnalités et paramètres, puis choisissez Modèles de création de référentiel.

  2. Sélectionnez Create template (Créer un modèle).

  3. Dans Détails du modèle, choisissez Pull through cache.

  4. Choisissez d'appliquer ce modèle à un préfixe spécifique ou à tous les référentiels qui ne correspondent pas à un autre modèle.

    Si vous choisissez Un préfixe spécifique, entrez la valeur du préfixe de l'espace de noms dans Préfixe. Vous avez spécifié ce préfixe lors de la création de la règle PTC.

  5. Choisissez Suivant.

  6. Dans la page de configuration de la création d'un référentiel, entrez les autorisations du référentiel. Utilisez l'un des exemples de déclarations de politique ou saisissez-en un similaire à l'exemple suivant :

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

  7. Vous pouvez éventuellement ajouter des paramètres de référentiel tels que la politique de cycle de vie et les balises. Amazon ECR applique ces règles à toutes les images de conteneur créées pour le cache d'extraction qui utilisent le préfixe spécifié.

  8. Choisissez Suivant.

  9. Vérifiez la configuration et choisissez Next.

Création du flux de travail

Lorsque vous créez un nouveau flux de travail ou une nouvelle version de flux de travail, passez en revue les mappages de registre et mettez-les à jour si nécessaire. Pour en savoir plus, consultez Création d'un flux de travail privé.

Mappages de registres

Vous définissez des mappages de registre pour mapper les préfixes de votre registre Amazon ECR privé et les noms de registre en amont.

Pour plus d'informations sur les mappages de registre Amazon ECR, consultez Création d'une règle de cache d'extraction dans Amazon ECR.

L'exemple suivant montre les mappages de registre vers Docker Hub, Quay et Amazon ECR Public.

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

Mappages d'images

Vous définissez des mappages d'images pour établir une correspondance entre les noms d'images tels que définis dans vos flux de travail Amazon ECR privés et les noms d'images dans le registre en amont.

Vous pouvez utiliser des mappages d'images avec des registres qui prennent en charge le pull through cache. Vous pouvez également utiliser des mappages d'images avec des registres en amont où le cache d'extraction HealthOmics n'est pas pris en charge. Vous devez synchroniser manuellement le registre en amont avec votre dépôt privé.

Pour plus d'informations sur les mappages d'images Amazon ECR, consultez Création d'une règle de cache d'extraction dans Amazon ECR.

L'exemple suivant montre les mappages entre des images Amazon ECR privées et une image génomique publique et la dernière image 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",
        }
    ]
}

Considérations générales relatives aux images de conteneurs Amazon ECR

  • Architecture

    HealthOmics prend en charge les conteneurs x86_64. Si votre machine locale est basée sur ARM, comme Apple Mac, utilisez une commande telle que la suivante pour créer une image de conteneur x86_64 : 

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

  • Point d'entrée et coque

    HealthOmics les moteurs de flux de travail injectent des scripts bash pour remplacer les commandes des images de conteneur utilisées par les tâches de flux de travail. Ainsi, les images de conteneur doivent être créées sans point d'entrée spécifié, de sorte qu'un shell bash soit le shell par défaut.

  • Chemins montés

    Un système de fichiers partagé est monté sur les tâches du conteneur dans /tmp. Toutes les données ou tous les outils intégrés à l'image du conteneur à cet emplacement seront remplacés.

    La définition du flux de travail est accessible aux tâches via un montage en lecture seule sur /mnt/workflow.

  • Taille de l'image

    Voir HealthOmics quotas de taille fixe du flux de travail pour les tailles maximales des images des conteneurs.

Variables d'environnement pour les HealthOmics flux de travail

HealthOmics fournit des variables d'environnement contenant des informations sur le flux de travail exécuté dans le conteneur. Vous pouvez utiliser les valeurs de ces variables dans la logique de vos tâches de flux de travail.

Toutes les variables HealthOmics de flux de travail commencent par le AWS_WORKFLOW_ préfixe. Ce préfixe est un préfixe de variable d'environnement protégée. N'utilisez pas ce préfixe pour vos propres variables dans les conteneurs de flux de travail.

HealthOmics fournit les variables d'environnement de flux de travail suivantes :

AWS_REGION

Cette variable correspond à la région dans laquelle le conteneur est exécuté.

AWS_WORKFLOW_EXÉCUTER

Cette variable est le nom de l'exécution en cours.

AWS_WORKFLOW_RUN_ID

Cette variable est l'identifiant de l'exécution en cours.

AWS_WORKFLOW_EXÉCUTER_UUID

Cette variable est l'UUID d'exécution de l'exécution en cours.

AWS_WORKFLOW_TÂCHE

Cette variable est le nom de la tâche en cours.

AWS_WORKFLOW_IDENTIFIANT DE TÂCHE

Cette variable est l'identifiant de la tâche en cours.

AWS_WORKFLOW_UUID DE TÂCHE

Cette variable est l'UUID de la tâche en cours.

L'exemple suivant montre les valeurs typiques de chaque variable d'environnement :

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

Utilisation de Java dans les images de conteneurs Amazon ECR

Si une tâche de flux de travail utilise une application Java telle que GATK, tenez compte des exigences de mémoire suivantes pour le conteneur :

  • Les applications Java utilisent de la mémoire en pile et de la mémoire en tas. Par défaut, la mémoire de segment maximale est un pourcentage de la mémoire totale disponible dans le conteneur. Cette valeur par défaut dépend de la distribution et de la version de la JVM spécifiques. Consultez donc la documentation correspondante à votre machine virtuelle Java ou définissez explicitement le maximum de mémoire à l'aide des options de ligne de commande Java (telles que `-Xmx`).

  • Ne définissez pas la mémoire de segment maximale à 100 % de l'allocation de mémoire du conteneur, car la pile JVM nécessite également de la mémoire. De la mémoire est également requise pour le ramasse-miettes de la machine virtuelle Java et pour tout autre processus du système d'exploitation exécuté dans le conteneur.

  • Certaines applications Java, telles que GATK, peuvent utiliser des invocations de méthodes natives ou d'autres optimisations telles que des fichiers de mappage de mémoire. Ces techniques nécessitent des allocations de mémoire effectuées « hors segment », qui ne sont pas contrôlées par le paramètre de mémoire maximale de la JVM.

    Si vous savez (ou pensez) que votre application Java alloue de la mémoire hors segment, assurez-vous que l'allocation de mémoire aux tâches inclut les exigences en matière de mémoire externe.

    Si ces allocations hors segment entraînent un manque de mémoire du conteneur, vous ne verrez généralement pas d'OutOfMemoryerreur Java, car la JVM ne contrôle pas cette mémoire.

Ajouter des entrées de tâches à une image de conteneur Amazon ECR

Ajoutez tous les exécutables, bibliothèques et scripts nécessaires pour exécuter une tâche de flux de travail dans l'image Amazon ECR utilisée pour exécuter la tâche.

Il est recommandé d'éviter d'utiliser des scripts, des fichiers binaires et des bibliothèques externes à une image de conteneur de tâches. Cela est particulièrement important lorsque vous utilisez nf-core des flux de travail qui utilisent un bin répertoire dans le cadre du package de flux de travail. Bien que ce répertoire soit disponible pour la tâche de flux de travail, il est monté en tant que répertoire en lecture seule. Les ressources requises dans ce répertoire doivent être copiées dans l'image de la tâche et mises à disposition lors de l'exécution ou lors de la création de l'image de conteneur utilisée pour la tâche.

Voir HealthOmics quotas de taille fixe du flux de travail pour connaître la taille maximale de l'image de conteneur prise HealthOmics en charge.