Imagens de contêiner para fluxos de trabalho privados - AWS HealthOmics
Sincronização com registros de contêineres de terceirosConsiderações gerais sobre imagens de contêineres do Amazon ECRAdicionar entradas de tarefas a uma imagem do Amazon ECRUsando Java em imagens de contêiner do Amazon ECRAdicionar entradas de tarefas a uma imagem do Amazon ECR

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Imagens de contêiner para fluxos de trabalho privados

HealthOmics oferece suporte a imagens de contêineres hospedadas em repositórios privados do Amazon ECR. Você pode criar imagens de contêiner e enviá-las para o repositório privado. Você também pode usar seu registro privado do Amazon ECR como um cache para sincronizar o conteúdo dos registros upstream.

Seu repositório Amazon ECR deve residir na mesma AWS região da conta que está chamando o serviço. Uma pessoa diferente Conta da AWS pode possuir a imagem do contêiner, desde que o repositório de imagens de origem forneça as permissões apropriadas. Para obter mais informações, consulte Políticas para acesso entre contas ao Amazon ECR.

Recomendamos que você defina a imagem do contêiner do Amazon ECR URIs como parâmetros em seu fluxo de trabalho para que o acesso possa ser verificado antes do início da execução. Também facilita a execução de um fluxo de trabalho em uma nova região alterando o parâmetro Região.

nota

HealthOmics não oferece suporte a contêineres ARM e não oferece suporte ao acesso a repositórios públicos.

Para obter informações sobre como configurar as permissões do IAM HealthOmics para acessar o Amazon ECR, consulte. HealthOmics Permissões de recursos

Sincronização com registros de contêineres de terceiros

Você pode usar as regras de cache pull through do Amazon ECR para sincronizar repositórios em um registro upstream compatível com seus repositórios privados do Amazon ECR. Para obter mais informações, consulte Sincronizar um registro upstream no Guia do usuário do Amazon ECR.

O cache de extração cria automaticamente o repositório de imagens em seu registro privado quando você cria o cache e sincroniza automaticamente com a imagem em cache quando há alterações na imagem upstream.

HealthOmics suporta cache pull through para os seguintes registros upstream:

  • Amazon ECR Public

  • Registro de imagens de contêineres do Kubernetes

  • Quay

  • Docker Hub

  • Microsoft Azure Container Registry

  • GitHub Registro de contêiner

  • GitLab Registro de contêiner

HealthOmics não suporta cache pull through para um repositório privado upstream do Amazon ECR.

Os benefícios de usar o cache pull through do Amazon ECR incluem:

  1. Você evita ter que migrar manualmente as imagens do contêiner para o Amazon ECR ou sincronizar atualizações do repositório de terceiros.

  2. Os fluxos de trabalho acessam as imagens sincronizadas do contêiner em seu repositório privado, o que é mais confiável do que baixar conteúdo em tempo de execução de um registro público.

  3. Como os caches pull through do Amazon ECR usam uma estrutura de URI previsível, o HealthOmics serviço pode mapear automaticamente o URI privado do Amazon ECR com o URI do registro upstream. Você não precisa atualizar e substituir os valores de URI na definição do fluxo de trabalho.

Configurando o cache pull through

O Amazon ECR fornece um registro para você Conta da AWS em cada região. Certifique-se de criar a configuração do Amazon ECR na mesma região em que planeja executar o fluxo de trabalho.

As seções a seguir descrevem as tarefas de configuração do cache pull through.

Crie uma regra de cache de pull through

Crie uma regra de cache pull through do Amazon ECR para cada registro upstream que tenha imagens que você deseja armazenar em cache. Uma regra especifica um mapeamento entre um registro upstream e o repositório privado do Amazon ECR.

Para um registro upstream que exija autenticação, você fornece suas credenciais usando o AWS Secrets Manager.

nota

Não altere uma regra de cache de pull through enquanto uma execução ativa estiver usando o repositório privado. A execução pode falhar ou, mais criticamente, fazer com que seu pipeline use imagens inesperadas.

Para obter mais informações, consulte Criação de uma regra de cache pull through no Guia do usuário do Amazon Elastic Container Registry.

Crie uma regra de cache de pull through usando o console

Para configurar o cache pull through, siga estas etapas usando o console do Amazon ECR:

  1. Abra o console do Amazon ECR: https://console.aws.amazon.com /ecr

  2. No menu à esquerda, em Registro privado, expanda Recursos e configurações. Em seguida, escolha Extrair pelo cache.

  3. Na página Pull through cache, escolha Adicionar regra.

  4. No painel Registro upstream, escolha o registro upstream para sincronizar com seu registro privado e, em seguida, escolha Avançar.

  5. Se o registro upstream exigir autenticação, o console abrirá uma nova página na qual você especifica o segredo de SageMaker IA que contém suas credenciais. Escolha Próximo.

  6. Em Especificar namespaces, no painel Namespace Cache, escolha se deseja criar os repositórios privados usando um prefixo de repositório específico ou sem prefixo. Se você optar por usar um prefixo, especifique o nome do prefixo em Prefixo do repositório de cache.

  7. No painel do namespace Upstream, escolha se deseja extrair dos repositórios upstream usando um prefixo de repositório específico ou sem prefixo. Se você optar por usar um prefixo, especifique o nome do prefixo no prefixo do repositório Upstream.

    O painel de exemplo de Namespace mostra um exemplo de pull request, URL upstream e a URL do repositório de cache criado.

  8. Escolha Próximo.

  9. Revise a configuração e escolha Criar para criar a regra.

Para obter mais informações, consulte Criar uma regra de cache de pull through (AWS Management Console).

Crie uma regra de cache de pull through usando a CLI

Use o create-pull-through-cache-rule comando Amazon ECR para criar uma regra de cache pull through. Para registros upstream que exigem autenticação, armazene as credenciais em um segredo do Secrets Manager.

As seções a seguir fornecem exemplos para cada registro upstream compatível.

O exemplo a seguir cria uma regra de cache de pull-through para o registro público do Amazon ECR. Ele especifica um prefixo de repositório de ecr-public, o que faz com que cada repositório criado usando a regra de cache de pull-through receba o esquema de nomes 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

O exemplo a seguir cria uma regra de cache de pull-through para o registro público do Kubernetes. Ele especifica um prefixo de repositório de kubernetes, o que faz com que cada repositório criado usando a regra de cache de pull-through receba o esquema de nomes 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

O exemplo a seguir cria uma regra de cache de pull-through para o registro público do Quay. Ele especifica um prefixo de repositório de quay, o que faz com que cada repositório criado usando a regra de cache de pull-through receba o esquema de nomes 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

O exemplo a seguir cria uma regra de cache de pull-through para o registro do Docker Hub. Ele especifica um prefixo de repositório de docker-hub, o que faz com que cada repositório criado usando a regra de cache de pull-through receba o esquema de nomes de docker-hub/upstream-repository-name. É necessário especificar o nome completo do Amazon Resource Name (ARN) do segredo que contém suas credenciais do 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

O exemplo a seguir cria uma regra de cache pull through para o GitHub Container Registry. Ele especifica um prefixo de repositório de github, o que faz com que cada repositório criado usando a regra de cache de pull-through receba o esquema de nomes de github/upstream-repository-name. Você deve especificar o Amazon Resource Name (ARN) completo do segredo que contém suas credenciais do 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

O exemplo a seguir cria uma regra de cache de pull-through para o Microsoft Azure Container Registry. Ele especifica um prefixo de repositório de azure, o que faz com que cada repositório criado usando a regra de cache de pull-through receba o esquema de nomes de azure/upstream-repository-name. É necessário especificar o nome completo do Amazon Resource Name (ARN) do segredo que contém suas credenciais do Docker Hub.

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

O exemplo a seguir cria uma regra de cache pull through para o GitLab Container Registry. Ele especifica um prefixo de repositório de gitlab, o que faz com que cada repositório criado usando a regra de cache de pull-through receba o esquema de nomes de gitlab/upstream-repository-name. Você deve especificar o Amazon Resource Name (ARN) completo do segredo que contém suas credenciais do 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 obter mais informações, consulte Criar uma regra de cache pull through (CLI) no Guia do usuário do Amazon ECR.

Você pode usar o comando get-run-task CLI para recuperar informações sobre a imagem do contêiner usada para uma tarefa específica:

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

A saída inclui as seguintes informações sobre a imagem do contêiner:

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

Permissões de registro para registro upstream

Use as permissões de registro HealthOmics para permitir o uso do cache de extração e a inserção das imagens do contêiner no registro privado do Amazon ECR. Adicione uma política de registro do Amazon ECR ao registro que fornece os contêineres usados nas execuções.

A política a seguir concede permissão para que o HealthOmics serviço crie repositórios com os prefixos de cache pull through especificados e inicie pulls upstream nesses repositórios.

  1. No console do Amazon ECR, abra o menu à esquerda, em Registro privado, expanda Permissões do registro. Em seguida, escolha Gerar declaração.

  2. No canto superior direito, escolha JSON. Insira uma política semelhante à seguinte:

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

Modelos de criação de repositório

Para usar o cache pull through HealthOmics, o repositório Amazon ECR deve ter um modelo de criação de repositório. O modelo define as configurações para quando você ou o Amazon ECR criam um repositório privado para um registro upstream.

Cada modelo contém um prefixo de namespace de repositório, que o Amazon ECR usa para combinar novos repositórios com um modelo específico. Os modelos especificam a configuração de todas as configurações do repositório, incluindo políticas de acesso baseadas em recursos, imutabilidade de tags, criptografia e políticas de ciclo de vida.

Para obter mais informações, consulte Modelos de criação de repositórios no Guia do usuário do Amazon Elastic Container Registry.

Como criar um modelo de criação de repositório:

  1. No console do Amazon ECR, abra o menu à esquerda, em Registro privado, expanda Recursos e configurações. Em seguida, escolha Modelos de criação de repositório.

  2. Selecione Criar modelo.

  3. Em Detalhes do modelo, escolha Extrair cache.

  4. Escolha se deseja aplicar esse modelo a um prefixo específico ou a todos os repositórios que não correspondam a outro modelo.

    Se você escolher Um prefixo específico, insira o valor do prefixo do namespace em Prefixo. Você especificou esse prefixo ao criar a regra PTC.

  5. Escolha Próximo.

  6. Na página Adicionar configuração de criação de repositório, insira Permissões do repositório. Use um dos exemplos de declarações de política ou insira um semelhante ao exemplo a seguir:

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

  7. Opcionalmente, você pode adicionar configurações do repositório, como políticas de ciclo de vida e tags. O Amazon ECR aplica essas regras a todas as imagens de contêiner criadas para o cache pull through que usam o prefixo especificado.

  8. Escolha Próximo.

  9. Revise a configuração e escolha Avançar.

Criação do fluxo de trabalho

Ao criar um novo fluxo de trabalho ou versão do fluxo de trabalho, revise os mapeamentos do registro e atualize-os, se necessário. Para obter detalhes, consulte Crie um fluxo de trabalho privado.

Mapeamentos de registro

Você define mapeamentos de registro para mapear entre prefixos em seu registro privado do Amazon ECR e os nomes de registro upstream.

Para obter mais informações sobre mapeamentos de registro do Amazon ECR, consulte Criação de uma regra de cache pull through no Amazon ECR.

O exemplo a seguir mostra mapeamentos de registro para 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"
        }
    ]
}

Mapeamentos de imagens

Você define mapeamentos de imagem para mapear entre os nomes das imagens, conforme definido em seus fluxos de trabalho privados do Amazon ECR, e os nomes das imagens no registro upstream.

Você pode usar mapeamentos de imagem com registros que oferecem suporte ao cache pull through. Você também pode usar mapeamentos de imagem com registros upstream que HealthOmics não suportam pull through cache. Você precisa sincronizar manualmente o registro upstream com seu repositório privado.

Para obter mais informações sobre mapeamentos de imagens do Amazon ECR, consulte Criação de uma regra de cache pull through no Amazon ECR.

O exemplo a seguir mostra mapeamentos de imagens privadas do Amazon ECR para uma imagem genômica pública e a imagem mais recente do 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",
        }
    ]
}

Considerações gerais sobre imagens de contêineres do Amazon ECR

  • Arquitetura

    HealthOmics suporta contêineres x86_64. Se sua máquina local for baseada em ARM, como o Apple Mac, use um comando como o seguinte para criar uma imagem de contêiner x86_64: 

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

  • Ponto de entrada e concha

    HealthOmics os mecanismos de fluxo de trabalho injetam scripts bash como uma substituição de comando nas imagens de contêiner usadas pelas tarefas do fluxo de trabalho. Portanto, as imagens de contêiner devem ser criadas sem um ENTRYPOINT especificado, de forma que um shell bash seja o padrão.

  • Caminhos montados

    Um sistema de arquivos compartilhado é montado nas tarefas do contêiner em /tmp. Todos os dados ou ferramentas incorporados à imagem do contêiner nesse local serão substituídos.

    A definição do fluxo de trabalho está disponível para tarefas por meio de uma montagem somente para leitura em /mnt/workflow.

  • Tamanho da imagem

    Consulte HealthOmics cotas de tamanho fixo do fluxo de trabalho os tamanhos máximos de imagem do contêiner.

Variáveis de ambiente para HealthOmics fluxos de trabalho

HealthOmics fornece variáveis de ambiente que têm informações sobre o fluxo de trabalho em execução no contêiner. Você pode usar os valores dessas variáveis na lógica das tarefas do seu fluxo de trabalho.

Todas as variáveis do HealthOmics fluxo de trabalho começam com o AWS_WORKFLOW_ prefixo. Esse prefixo é um prefixo de variável de ambiente protegido. Não use esse prefixo para suas próprias variáveis em contêineres de fluxo de trabalho.

HealthOmics fornece as seguintes variáveis de ambiente de fluxo de trabalho:

AWS_REGION

Essa variável é a região em que o contêiner está sendo executado.

AWS_WORKFLOW_EXECUTAR

Essa variável é o nome da execução atual.

AWS_WORKFLOW_ID DE EXECUÇÃO

Essa variável é o identificador da execução atual.

AWS_WORKFLOW_EXECUTAR UUID

Essa variável é o UUID de execução da execução atual.

AWS_WORKFLOW_TAREFA

Essa variável é o nome da tarefa atual.

AWS_WORKFLOW_ID DA TAREFA

Essa variável é o identificador da tarefa atual.

AWS_WORKFLOW_TASK_UUID

Essa variável é o UUID da tarefa atual.

O exemplo a seguir mostra valores típicos para cada variável de 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

Usando Java em imagens de contêiner do Amazon ECR

Se uma tarefa de fluxo de trabalho usa um aplicativo Java, como o GATK, considere os seguintes requisitos de memória para o contêiner:

  • Os aplicativos Java usam memória de pilha e memória de pilha. Por padrão, a memória máxima da pilha é uma porcentagem da memória total disponível no contêiner. Esse padrão depende da distribuição específica da JVM e da versão da JVM, portanto, consulte a documentação relevante da sua JVM ou defina explicitamente o máximo de memória do heap usando as opções da linha de comando Java (como `-Xmx`).

  • Não defina a memória máxima do heap como 100% da alocação de memória do contêiner, pois a pilha da JVM também requer memória. A memória também é necessária para o coletor de lixo da JVM e para qualquer outro processo do sistema operacional em execução no contêiner.

  • Alguns aplicativos Java, como o GATK, podem usar invocações de métodos nativos ou outras otimizações, como arquivos de mapeamento de memória. Essas técnicas exigem alocações de memória executadas “fora da pilha”, que não são controladas pelo parâmetro máximo de pilha da JVM.

    Se você sabe (ou suspeita) que seu aplicativo Java aloca memória fora da pilha, certifique-se de que sua alocação de memória de tarefas inclua os requisitos de memória fora da pilha.

    Se essas alocações fora do heap fizerem com que o contêiner fique sem memória, você normalmente não verá um OutOfMemory erro de Java, porque a JVM não controla essa memória.

Adicionar entradas de tarefas a uma imagem de contêiner do Amazon ECR

Adicione todos os executáveis, bibliotecas e scripts necessários para executar uma tarefa de fluxo de trabalho na imagem do Amazon ECR usada para executar a tarefa.

É uma prática recomendada evitar o uso de scripts, binários e bibliotecas externos à imagem do contêiner de tarefas. Isso é especialmente importante ao usar nf-core fluxos de trabalho que usam um bin diretório como parte do pacote de fluxo de trabalho. Embora esse diretório esteja disponível para a tarefa do fluxo de trabalho, ele é montado como um diretório somente para leitura. Os recursos necessários nesse diretório devem ser copiados na imagem da tarefa e disponibilizados em tempo de execução ou ao criar a imagem do contêiner usada para a tarefa.

Consulte HealthOmics cotas de tamanho fixo do fluxo de trabalho o tamanho máximo da imagem do contêiner HealthOmics compatível.