View a markdown version of this page

创建私有工作流程 - AWS HealthOmics

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

创建私有工作流程

使用创建工作流程 HealthOmics 控制台, AWS CLI 命令,或其中一个 AWS 软件开发工具包。

注意

不要在工作流程名称中包含任何个人身份信息 (PII)。这些名称可见于 CloudWatch 日志。

当你创建工作流程时, HealthOmics 为工作流程分配通用唯一标识符 (UUID)。工作流程 UUID 是全球唯一标识符 (guid),在工作流程和工作流程版本中是唯一的。出于数据来源的目的,我们建议您使用工作流程 UUID 来唯一标识工作流程。

如果您的工作流程任务使用任何外部工具(可执行文件、库或脚本),则可以将这些工具构建到容器映像中。您可以通过以下方式托管容器镜像:

  • 在 ECR 私有注册表中托管容器镜像。此选项的先决条件:

    • 创建 ECR 私有存储库,或选择现有存储库。

    • 按照中的说明配置 ECR 资源策略 Amazon ECR 权限。

    • 将您的容器镜像上传到私有存储库。

  • 将容器映像与支持的第三方注册表的内容同步。此选项的先决条件:

    • 在 ECR 私有注册表中,为每个上游注册表配置拉取缓存规则。有关更多信息,请参阅 镜像映射。

    • 按照中的说明配置 ECR 资源策略 Amazon ECR 权限。

    • 创建存储库创建模板。该模板定义了 Amazon ECR 何时为上游注册表创建私有存储库的设置。

    • 创建前缀映射,将工作流程定义中的容器映像引用重新映射到 ECR 缓存命名空间。

创建工作流时,您提供的工作流定义,其中包含有关工作流、运行和任务的信息。 HealthOmics 可以检索存储在本地或 Amazon S3 存储桶中的.zip 存档形式的工作流程定义,或者从支持的 Git-based 存储库。

使用控制台创建工作流程

创建工作流程的步骤
  1. 打开 HealthOmics 控制台。

  2. 如果需要,请打开左侧导航窗格 (≡)。选择 私人工作流程。

  3. 在 私人工作流程 页面,选择 创建工作流程。

  4. 在 定义工作流程 页面,提供以下信息:

    1. 工作流程名称:此工作流程的独特名称。我们建议设置工作流程名称,将您的运行组织在 AWS HealthOmics 控制台和 CloudWatch 日志。

    2. 描述 (可选):此工作流程的描述。

  5. 在 工作流程定义 面板,提供以下信息:

    1. 工作流程语言 (可选):选择工作流程的规范语言。否则, HealthOmics 根据工作流程定义确定语言。

    2. 对于 工作流程定义来源,选择从 a 导入定义文件夹 Git-based 存储库、Amazon S3 位置或来自本地驱动器。

      1. 对于 从存储库服务导入:

        注意

        HealthOmics 支持公共和私有存储库 GitHub, GitLab, Bitbucket, GitHub self-managed, GitLab self-managed。

        1. 选择一个 连接 连接你的 AWS 资源到外部存储库。要创建连接,请参见 连接外部代码存储库。

          注意

          客户在 TLV 区域需要在中创建连接 IAD (us-east-1) 区域用于创建工作流程。

        2. 在 完整存储库 ID,以用户身份输入您的存储库 ID-name/repo-名称。确认您有权访问此存储库中的文件。

        3. 在 来源参考 (可选),输入存储库源引用(分支、标签或提交 ID)。 HealthOmics 如果未指定源引用,则使用默认分支。

        4. 在 排除文件模式,输入文件模式以排除特定的文件夹、文件或扩展名。这有助于在导入存储库文件时管理数据大小。最多有 50 个图案,并且图案必须遵循 glob 模式语法。例如:

          1. tests/

          2. *.jpeg

          3. large_data.zip

      2. 对于 从 S3 中选择定义文件夹:

        1. 输入包含压缩工作流程定义文件夹的 Amazon S3 位置。Amazon S3 存储桶必须与工作流程位于同一区域。

        2. 如果您的账户不拥有 Amazon S3 存储桶,请输入存储桶所有者的 AWS 中的账户 ID S3 存储桶所有者的账户 ID。此信息是必需的,以便 HealthOmics 可以验证存储桶所有权。

      3. 对于 从本地源中选择定义文件夹:

        1. 输入压缩的工作流定义文件夹的本地驱动器位置。

    3. 主工作流程定义文件路径 (可选):输入从压缩的工作流定义文件夹或存储库到 main 文件。如果工作流定义文件夹中只有一个文件,或者主文件名为 “main”,则不需要此参数。

  6. 在 自述文件 (可选)面板,选择 自述文件来源 并提供以下信息:

    • 对于 从存储库服务导入,在 自述文件路径,输入存储库中 README 文件的路径。

    • 对于 从 S3 中选择文件,在 S3 中的 README 文件,输入自述文件的 Amazon S3 URI。

    • 对于 从本地源中选择文件: 在 自述文件-可选,选择 选择文件 选择要上传的 markdown (.md) 文件。

  7. 在 默认运行存储配置 面板,为使用此工作流程的运行提供默认运行存储类型和容量:

    1. 运行存储类型:选择使用静态存储还是动态存储作为临时运行存储的默认存储。默认为静态存储。

    2. 运行存储容量 (可选):对于静态运行存储类型,您可以输入此工作流程所需的默认运行存储量。此参数的默认值为 1200 GiB。当你开始运行时,你可以覆盖这些默认值。

  8. 标签 (可选):您最多可以将 50 个标签与该工作流程关联。

  9. 选择下一步。

  10. 在 添加工作流程参数 (可选)页面,选择 参数来源:

    1. 对于 从工作流定义文件中解析, HealthOmics 将自动解析工作流定义文件中的工作流参数。

    2. 对于 提供来自 Git 存储库的参数模板,使用存储库中参数模板文件的路径。

    3. 对于 从本地源中选择 JSON 文件,上传一个 JSON 来自本地来源的文件,用于指定参数。

    4. 对于 手动输入工作流程参数,手动输入参数名称和描述。

  11. 在 参数预览 面板,您可以查看或更改此工作流程版本的参数。如果你恢复 JSON 文件,您会丢失所做的任何本地更改。

  12. 选择下一步。

  13. 在 容器 URI 重映射 页面,在 映射规则 面板,您可以为工作流程定义 URI 映射规则。

    对于 映射文件来源,选择以下选项之一:

    • 没有 — 无需映射规则。

    • 从 S3 中选择 JSON 文件 — 指定映射文件的 S3 位置。

    • 从本地源中选择 JSON 文件 — 指定本地设备上的映射文件位置。

    • 手动输入映射 — 在中输入注册表映射和映像映射 映射 面板。

  14. 控制台显示 映射 面板。如果选择映射源文件,控制台将显示该文件中的值。

    1. 在 注册表映射,您可以编辑映射或添加映射(最多 20 个注册表映射)。

      每个注册表映射都包含以下字段:

      • 上游注册表 URL — 上游注册表的 URI。

      • ECR 存储库前缀 — 在 Amazon ECR 私有存储库中使用的存储库前缀。

      • (可选) 上游存储库前缀 — 上游注册表中存储库的前缀。

      • (可选) ECR 账户 ID — 拥有上游容器镜像的账户的账户 ID。

      • (可选) 凭证 ARN — 包含您的注册表凭据的密钥管理器密钥的 ARN。对于亚马逊 ECR 提取缓存不支持的注册表,例如 Seqera、NVIDIA NGC、谷歌神器注册表和谷歌容器注册表是必需的。有关更多信息,请参阅 使用拉入式缓存不支持的第三方注册表。

    2. 在 图像映射,您可以编辑图像映射或添加映射(最多 100 个图像映射)。

      每个图像映射都包含以下字段:

      • 源图片 — 指定上游注册表中源图像的 URI。

      • 目标图片 — 指定私有亚马逊 ECR 注册表中相应图像的 URI。

  15. 选择下一步。

  16. 查看工作流程配置,然后选择 创建工作流程。

使用 CLI 创建工作流程

如果您的工作流程文件和参数模板文件位于本地计算机上,则可以使用以下 CLI 命令创建工作流程。

aws omics create-workflow \ --name "my_workflow" \ --definition-zip fileb://my-definition.zip \ --parameter-template file://my-parameter-template.json

这个 create-workflow 操作返回以下响应:

{ "arn": "arn:aws:omics:us-west-2:....", "id": "1234567", "status": "CREATING", "tags": { "resourceArn": "arn:aws:omics:us-west-2:...." }, "uuid": "64c9a39e-8302-cc45-0262-2ea7116d854f" }

创建工作流程时使用的可选参数

创建工作流程时,您可以指定任何可选参数。有关语法的详细信息,请参见 CreateWorkflow 在 AWS 中 HealthOmics API 参考。

指定工作流程定义 Amazon S3 位置

如果您的工作流程定义文件位于 Amazon S3 文件夹中,请使用指定位置 definition-uri 参数,如以下示例所示。如果您的账户不拥有 Amazon S3 存储桶,请提供所有者的 AWS 账户 ID。

aws omics create-workflow \ --name Test \ --definition-uri s3://omics-bucket/workflow-definition/ \ --owner-id 123456789012 ...

使用来自的工作流定义 Git-based 知识库

使用支持的工作流定义 Git-based 存储库,使用 definition-repository 您的请求中的参数。不要提供其他任何东西 definition 参数,因为如果请求包含多个输入源,则请求会失败。

这个 definition-respository 参数包含以下字段:

  • connectionArn — 将您的 AWS 资源连接到外部存储库的代码连接的 ARN。

  • fullRepositoryId — 将存储库 ID 输入为 owner-name/repo-name。确认您有权访问此存储库中的文件。

  • sourceReference (可选)-输入存储库引用类型(BRANCH、TAG 或 COMMIT)和值。

    HealthOmics 如果您未指定源代码引用,则使用默认分支上的最新提交。

  • excludeFilePatterns (可选)-输入文件模式以排除特定的文件夹、文件或扩展名。这有助于在导入存储库文件时管理数据大小。最多提供 50 个图案。图案必须遵循 glob 模式语法。例如:

    • tests/

    • *.jpeg

    • large_data.zip

当您从中指定工作流定义时 Git-based 存储库,使用 parameter-template-path 指定参数模板文件。如果你不提供这个参数, HealthOmics 创建没有参数模板的工作流程。

以下示例显示了与来自的内容相关的参数 Git-based 私人存储库:

aws omics create-workflow \ --name custom-variant \ --description "Custom variant calling pipeline" \ --engine "WDL" \ --definition-repository '{ "connectionArn": "arn:aws:codeconnections:us-east-1:123456789012:connection/abcd1234-5678-90ab-cdef-1234567890ab", "fullRepositoryId": "myorg/my-genomics-workflows", "sourceReference": { "type": "BRANCH", "value": "main" }, "excludeFilePatterns": ["tests/**", "*.log"] }' \ --main "workflows/variant-calling/main.wdl" \ --parameter-template-path "parameters/variant-calling-params.json" \ --readme-path "docs/variant-calling-README.md" \ --storage-type "DYNAMIC" \

更多示例,请参阅博客文章 如何创建 AWS HealthOmics 基于 Git 内容的工作流程。

指定自述文件

您可以使用以下参数之一指定 README 文件位置:

  • readme-markdown — 字符串输入或本地计算机上的文件。

  • readme-uri — 存储在 S3 上的文件的 URI。

  • readme-path — 存储库中自述文件的路径。

只能将 readme-path 与一起使用 定义存储库。如果你没有指定任何 README 参数, HealthOmics 导入根级别 README.md 存储库中的文件(如果存在)。

以下示例显示如何使用自述文件路径和自述文件路径指定自述文件位置。

# Using README from repository aws omics create-workflow \ --name "documented-workflow" \ --definition-repository '...' \ --readme-path "docs/workflow-guide.md" # Using README from S3 aws omics create-workflow \ --name "s3-readme-workflow" \ --definition-repository '...' \ --readme-uri "s3://my-bucket/workflow-docs/readme.md"

有关更多信息,请参阅 HealthOmics 工作流程自述文件。

指定 main 定义文件

如果您包含多个工作流程定义文件,请使用 main 参数来指定工作流程的主定义文件。

aws omics create-workflow \ --name Test \ --main multi_workflow/workflow2.wdl \ ...

指定运行存储类型

您可以指定默认运行存储类型(动态或静态)和运行存储容量(静态存储必需)。有关运行存储类型的更多信息,请参阅 在 HealthOmics 工作流程中运行存储类型。

aws omics create-workflow \ --name my_workflow \ --definition-zip fileb://my-definition.zip \ --parameter-template file://my-parameter-template.json \ --storage-type 'STATIC' \ --storage-capacity 1200 \

指定 GPU 配置

使用加速器参数创建在加速计算实例上运行的工作流程。以下示例显示了如何使用 accelerators 参数。您在工作流程定义中指定 GPU 配置。请参阅Accelerated-computing 实例。

aws omics create-workflow --name workflow name \ --definition-uri s3://amzn-s3-demo-bucket1/GPUWorkflow.zip \ --accelerators GPU

配置拉入式缓存映射参数

如果您使用的是 Amazon ECR 提取缓存映射功能,则可以覆盖默认映射。 HealthOmics 支持第三方容器注册表,例如 Amazon ECR Public、Kubernetes 容器镜像注册表、Quay、Docker Hub、微软 Azure 容器注册表、 GitHub 容器注册表,以及 GitLab 容器注册表。有关容器设置参数的更多信息,请参阅 私有工作流程的容器镜像。

在以下示例中,文件 mappings.json 包含以下内容:

{ "registryMappings": [ { "upstreamRegistryUrl": "registry-1.docker.io", "ecrRepositoryPrefix": "docker-hub" }, { "upstreamRegistryUrl": "quay.io", "ecrRepositoryPrefix": "quay", "ecrAccountId": "111122223333" }, { "upstreamRegistryUrl": "public.ecr.aws", "ecrRepositoryPrefix": "ecr-public" } ], "imageMappings": [{ "sourceImage": "docker.io/library/ubuntu:latest", "destinationImage": "111122223333.dkr.ecr.us-east-1.amazonaws.com/healthomics-docker-2/custom/ubuntu:latest" }, { "sourceImage": "nvcr.io/nvidia/k8s/dcgm-exporter", "destinationImage": "111122223333.dkr.ecr.us-east-1.amazonaws.com/healthomics-nvidia/k8s/dcgm-exporter" } ] }

在 create-workflow 命令中指定映射参数:

aws omics create-workflow \ ... --container-registry-map file://mappings.json ...

您还可以指定映射参数文件的 S3 位置:

aws omics create-workflow \ ... --container-registry-map-uri s3://amzn-s3-demo-bucket1/test.zip ...

配置非拉取式缓存映射参数

如果您使用来自不支持提取缓存的注册表中的容器镜像,请添加 credentialArn 到注册表的每个映射 HealthOmics 从 ARN 复制并使用完整机密 ARN。有关更多信息,请参阅 使用拉入式缓存不支持的第三方注册表。

在以下示例中,文件 mappings.json 包含以下内容:

{ "registryMappings": [ { "upstreamRegistryUrl": "community.wave.seqera.io", "ecrRepositoryPrefix": "wave-seqera", "credentialArn": "arn:aws:secretsmanager:us-east-1:111122223333:secret:omics-registry/seqera-EXAMPLE" }, { "upstreamRegistryUrl": "nvcr.io", "ecrRepositoryPrefix": "nvidia-ngc", "credentialArn": "arn:aws:secretsmanager:us-east-1:111122223333:secret:omics-registry/nvidia-ngc-EXAMPLE" } ] }

在 create-workflow 命令中指定映射参数:

aws omics create-workflow \ ... --container-registry-map file://mappings.json ...

您也可以内联提供注册表映射。以下示例使用行内注册表映射为 Seqera 容器创建了一个工作流程:

aws omics create-workflow \ --name my-workflow \ --engine NEXTFLOW \ --definition-uri s3://amzn-s3-demo-bucket1/my-definition.zip \ --container-registry-map '{ "registryMappings": [ { "upstreamRegistryUrl": "community.wave.seqera.io", "ecrRepositoryPrefix": "wave-seqera", "credentialArn": "arn:aws:secretsmanager:us-east-1:111122223333:secret:omics-registry/seqera-EXAMPLE" } ] }'

使用 SDK 创建工作流程

您可以使用其中一个 SDK 创建工作流程。以下示例显示如何使用 Python SDK 创建工作流程

import boto3 omics = boto3.client('omics') with open('definition.zip', 'rb') as f: definition = f.read() response = omics.create_workflow( name='my_workflow', definitionZip=definition, parameterTemplate={ ... } )