与第三方容器注册表同步 Amazon ECR 容器镜像的一般注意事项向 Amazon ECR 图像添加任务输入在 Amazon ECR 容器镜像中使用 Java 向 Amazon ECR 图像添加任务输入

私有工作流程的容器镜像

HealthOmics 支持托管在 Amazon ECR 私有存储库中的容器映像。您可以创建容器镜像并将其上传到私有存储库。您还可以将 Amazon ECR 私有注册表作为直通缓存，以同步上游注册表的内容。

您的 Amazon ECR 存储库必须与调用该服务的账户位于同一 AWS 区域。只要源镜像存储库提供适当的权限，其他人 AWS 账户就可以拥有容器镜像。有关更多信息，请参阅跨账户 Amazon ECR 访问政策。

我们建议您将您的 Amazon ECR 容器映 URIs 像定义为工作流程中的参数，以便在运行开始之前可以验证访问权限。通过更改 Region 参数，还可以更轻松地在新区域中运行工作流程。

注意

HealthOmics 不支持 ARM 容器，也不支持访问公共仓库。

有关为访问 Amazon ECR 配置 IAM 权限的信息，请参阅HealthOmics 资源权限。 HealthOmics

与第三方容器注册表同步

您可以使用 Amazon ECR 提取缓存规则将支持的上游注册表中的存储库与您的 Amazon ECR 私有存储库同步。有关更多信息，请参阅 Amazon ECR 用户指南中的同步上游注册表。

创建缓存时，直通缓存会自动在您的私有注册表中创建图像存储库，当上游图像发生更改时，它会自动与缓存的图像同步。

HealthOmics 支持以下上游注册表的直通缓存：

Amazon ECR Public
Kubernetes 容器镜像注册表
Quay
Docker Hub
Microsoft Azure 容器注册表
GitHub 容器注册表
GitLab 容器注册表

HealthOmics 不支持上游 Amazon ECR 私有存储库的直通缓存。

使用 Amazon ECR 直通缓存的好处包括：

您无需手动将容器映像迁移到 Amazon ECR 或同步来自第三方存储库的更新。
工作流程可以访问私有存储库中的同步容器镜像，这比在运行时从公共注册表下载内容更可靠。
由于 Amazon ECR 提取缓存使用可预测的 URI 结构，因此该 HealthOmics 服务可以自动将 Amazon ECR 私有 URI 与上游注册表 URI 映射。您无需更新和替换工作流程定义中的 URI 值。

主题

配置直通缓存
注册表映射
镜像映射

配置直通缓存

Amazon ECR AWS 账户在每个区域都为您提供了一个注册表。请务必在计划运行工作流程的同一区域创建 Amazon ECR 配置。

以下各节描述了直通缓存的配置任务。

配置任务

创建直通缓存规则
上游注册表的注册表权限
存储库创建模板
创建工作流

创建直通缓存规则

为每个包含要缓存的图像的上游注册表创建 Amazon ECR 拉取缓存规则。规则指定了上游注册表和 Amazon ECR 私有存储库之间的映射。

对于需要身份验证的上游注册表，您可以使用 AWS Secrets Manager 提供证书。

注意

当活动运行使用私有存储库时，请勿更改拉取缓存规则。运行可能会失败，或者更严重的是，会导致您的管道使用意想不到的图像。

有关更多信息，请参阅 Amazon Elastic Container Registry 用户指南中的创建直通缓存规则。

使用控制台创建直通缓存规则

要配置直通缓存，请使用 Amazon ECR 控制台执行以下步骤：

打开 Amazon ECR 控制台： https://console.aws.amazon.com/ecr
在左侧菜单的 “私有注册表” 下，展开 “功能和设置”。然后选择 P ull through cache。
从 P ull through 缓存页面中，选择添加规则。
在上游注册表面板中，选择要与您的私有注册表同步的上游注册表，然后选择下一步。
如果上游注册表需要身份验证，则控制台会打开一个新页面，您可以在其中指定包含您的凭据的 SageMaker AI 密钥。选择下一步。
在 “指定命名空间” 下的 “缓存命名空间” 面板中，选择是使用特定的存储库前缀还是不使用前缀创建私有存储库。如果您选择使用前缀，请在缓存存储库前缀中指定前缀名称。
在 “上游命名空间” 面板中，选择是使用特定的存储库前缀还是不使用前缀从上游存储库提取。如果您选择使用前缀，请在上游存储库前缀中指定前缀名称。

命名空间示例面板显示拉取请求示例、上游 URL 和创建的缓存存储库的 URL。
选择下一步。
查看配置并选择创建以创建规则。

有关更多信息，请参阅创建直通缓存规则（AWS 管理控制台）。

使用 CLI 创建直通缓存规则

使用 Amazon ECR create-pull-through-cache-rule 命令创建直通缓存规则。对于需要身份验证的上游注册表，请将凭据存储在 Secrets Manager 密钥中。

以下各节提供了每个支持的上游注册表的示例。

以下示例为 Amazon ECR 公有注册表创建一个缓存提取规则。它指定了存储库前缀 ecr-public，这导致使用缓存提取规则创建的每个存储库都具有 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

以下示例为 Kubernetes 公有注册表创建了一个缓存提取规则。它指定了存储库前缀 kubernetes，这导致使用缓存提取规则创建的每个存储库都具有 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

以下示例为 Quay 公有注册表创建了一个缓存提取规则。它指定了存储库前缀 quay，这导致使用推送缓存规则创建的每个存储库都具有命名方案 quay/upstream-repository-name。


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

以下示例为 Docker Hub 注册表创建了一个缓存提取规则。它指定了存储库前缀 docker-hub，这导致使用缓存提取规则创建的每个存储库都具有 docker-hub/upstream-repository-name 命名方案。您必须指定包含 Docker Hub 凭证的密钥的完整 Amazon 资源名称（ARN）。


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

以下示例为 GitHub 容器注册表创建了通过缓存规则。它指定了存储库前缀 github，这导致使用缓存提取规则创建的每个存储库都具有 github/upstream-repository-name 命名方案。您必须指定包含您的 GitHub 容器注册凭证的密钥的完整 Amazon 资源名称 (ARN)。


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

以下示例为 Microsoft Azure 容器注册表创建了一个缓存提取规则。它指定了存储库前缀 azure，这导致使用缓存提取规则创建的每个存储库都具有 azure/upstream-repository-name 命名方案。您必须指定包含 Microsoft Azure 容器注册表凭证的密钥的完整 Amazon 资源名称（ARN）。


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

以下示例为 GitLab 容器注册表创建了通过缓存规则。它指定了存储库前缀 gitlab，这导致使用缓存提取规则创建的每个存储库都具有 gitlab/upstream-repository-name 命名方案。您必须指定包含您的 GitLab 容器注册凭证的密钥的完整 Amazon 资源名称 (ARN)。


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

有关更多信息，请参阅 Amazon ECR 用户指南中的创建直通缓存规则 (CLI)。

您可以使用 get-run-task CLI 命令来检索有关用于特定任务的容器镜像的信息：


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

输出包含有关容器镜像的以下信息：


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

上游注册表的注册表权限

使用注册表权限 HealthOmics 允许使用直通缓存并将容器映像提取到 Amazon ECR 私有注册表中。将 Amazon ECR 注册表策略添加到提供运行中使用的容器的注册表。

以下策略授予该 HealthOmics 服务创建具有指定拉取缓存前缀的存储库以及启动对这些存储库的上游拉取的权限。

在 Amazon ECR 控制台中，打开左侧菜单，在 “私有注册表” 下，展开 “注册表权限”。然后选择 “生成声明”。

在右上角，选择 JSON。输入类似于以下内容的策略：

存储库创建模板

要在中使用拉取缓存 HealthOmics，Amazon ECR 存储库必须具有存储库创建模板。该模板定义了您或 Amazon ECR 为上游注册表创建私有存储库时的配置设置。

每个模板都包含存储库命名空间前缀，Amazon ECR 使用该前缀将新存储库与特定模板进行匹配。模板指定所有存储库设置的配置，包括基于资源的访问策略、标签不可变性、加密和生命周期策略。

有关更多信息，请参阅 Amazon 弹性容器注册表用户指南中的存储库创建模板。

如何创建仓库创建模板：

在 Amazon ECR 控制台中，打开左侧菜单，在 “私有注册表” 下，展开 “功能和设置”。然后选择存储库创建模板。
选择创建模板。
在模板详细信息中，选择提取缓存。
选择是将此模板应用于特定的前缀，还是应用于所有与其他模板不匹配的存储库。

如果选择特定前缀，请在前缀中输入命名空间前缀值。您在创建 PTC 规则时指定了此前缀。
选择下一步。

在添加存储库创建配置页面中，输入存储库权限。使用其中一个示例策略声明，或输入类似于以下示例的声明：

或者，您可以添加仓库设置，例如生命周期策略和标签。Amazon ECR 将这些规则应用于为使用指定前缀的直通缓存创建的所有容器映像。
选择下一步。
查看配置并选择 “下一步”。

创建工作流

创建新的工作流程或工作流程版本时，请查看注册表映射并在需要时对其进行更新。有关更多信息，请参阅创建私有工作流程。

注册表映射

您可以定义注册表映射以在私有 Amazon ECR 注册表中的前缀和上游注册表名称之间进行映射。

有关 Amazon ECR 注册表映射的更多信息，请参阅在 A mazon ECR 中创建直通缓存规则。

以下示例显示了 Docker Hub、Quay 和 Amazon ECR Public 的注册表映射。


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

镜像映射

您可以定义映射以在私有 Amazon ECR 工作流程中定义的图像名称和上游注册表中的图像名称之间进行映射。

您可以将图像映射与支持直通缓存的注册表一起使用。您也可以将图像映射用于 HealthOmics 不支持直通缓存的上游注册表。您需要手动将上游注册表与您的私有存储库同步。

有关 Amazon ECR 图像映射的更多信息，请参阅在 A mazon ECR 中创建直通缓存规则。

以下示例显示了从私有 Amazon ECR 映像到公共基因组学映像和最新 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",
        }
    ]
}

Amazon ECR 容器镜像的一般注意事项

架构

HealthOmics 支持 x86_64 容器。如果您的本地计算机基于 ARM，例如 Apple Mac，请使用以下命令来构建 x86_64 容器镜像：
```
docker build --platform amd64 -t my_tool:latest .
```
入口点和外壳

HealthOmics 工作流引擎将 bash 脚本作为命令替换注入到工作流任务使用的容器镜像中。因此，应在没有指定的 ENTRYPOINT 的情况下构建容器映像，以便默认使用 bash shell。
已安装的路径

共享文件系统挂载到位于 /tmp 的容器任务。在此位置的容器镜像中内置的任何数据或工具都将被覆盖。

工作流定义可通过 /mnt/workflow 上的只读挂载供任务使用。
映像大小

HealthOmics 工作流程固定大小配额有关容器镜像的最大尺寸，请参阅。

HealthOmics 工作流程的环境变量

HealthOmics 提供了环境变量，这些变量包含有关容器中运行的工作流程的信息。您可以在工作流程任务的逻辑中使用这些变量的值。

所有 HealthOmics 工作流程变量都以AWS_WORKFLOW_前缀开头。此前缀是受保护的环境变量前缀。请勿在工作流程容器中为自己的变量使用此前缀。

HealthOmics 提供了以下工作流环境变量：

AWS_REGION: 此变量是容器运行的区域。
AWS_WORKFLOW_RUN: 此变量是当前运行的名称。
AWS_WORKFLOW_RUN_ID: 此变量是当前运行的运行标识符。
AWS_WORKFLOW_RUN_UUID: 此变量是当前运行的运行 UUID。
AWS_WORKFLOW_任务: 此变量是当前任务的名称。
AWS_WORKFLOW_任务_ID: 此变量是当前任务的任务标识符。
AWS_WORKFLOW_TASK_UUID: 此变量是当前任务的任务 UUID。

以下示例显示了每个环境变量的典型值：


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

在 Amazon ECR 容器镜像中使用 Java

如果工作流任务使用 Java 应用程序（例如 GATK），请考虑容器的以下内存要求：

Java 应用程序使用堆栈内存和堆内存。默认情况下，最大堆内存是容器中总可用内存的百分比。此默认值取决于特定的 JVM 发行版和 JVM 版本，因此请查阅 JVM 的相关文档，或者使用 Java 命令行选项（例如 `-Xmx）明确设置堆内存最大值。
不要将最大堆内存设置为容器内存分配的 100%，因为 JVM 堆栈也需要内存。JVM 垃圾收集器和容器中运行的任何其他操作系统进程也需要内存。
某些 Java 应用程序（例如 GATK）可以使用本机方法调用或其他优化，例如内存映射文件。这些技术需要在 “堆外” 执行的内存分配，这些分配不受JVM最大堆参数的控制。

如果您知道（或怀疑）您的 Java 应用程序分配了堆外内存，请确保您的任务内存分配包括堆外内存需求。

如果这些堆外分配导致容器内存不足，则通常不会看到 Java OutOfMemory 错误，因为 JVM 无法控制此内存。

向 Amazon ECR 容器镜像添加任务输入

将运行工作流程任务所需的所有可执行文件、库和脚本添加到用于运行该任务的 Amazon ECR 映像中。

最佳做法是避免使用任务容器镜像外部的脚本、二进制文件和库。当使用使用bin目录作为nf-core工作流包一部分的工作流时，这一点尤其重要。虽然此目录可供工作流任务使用，但它是作为只读目录安装的。应将此目录中的所需资源复制到任务镜像中，并在运行时或构建用于任务的容器映像时提供。

HealthOmics 工作流程固定大小配额有关 HealthOmics 支持的容器镜像的最大大小，请参阅。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

参数模板文件

可选：Sentieon 许可证