私有工作流程的容器映像 - AWS HealthOmics

本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。

私有工作流程的容器映像

HealthOmics 支援 Amazon ECR 私有儲存庫中託管的容器映像。您可以建立容器映像並將其上傳至私有儲存庫。您也可以將 Amazon ECR 私有登錄檔做為提取快取來同步上游登錄檔的內容。

您的 Amazon ECR 儲存庫必須與呼叫 服務的帳戶位於相同的 AWS 區域。只要來源映像儲存庫提供適當的許可,不同的 AWS 帳戶 就可以擁有容器映像。如需詳細資訊,請參閱跨帳戶 Amazon ECR 存取的政策

建議您將 Amazon ECR 容器映像 URIs定義為工作流程中的參數,以便在執行開始之前驗證存取權。變更區域參數也可讓您更輕鬆地在新區域中執行工作流程。

注意

HealthOmics 不支援 ARM 容器,也不支援存取公有儲存庫。

如需設定 HealthOmics 存取 Amazon ECR 的 IAM 許可的詳細資訊,請參閱 HealthOmics 資源許可

與第三方容器登錄檔同步

您可以使用 Amazon ECR 提取快取規則,將支援的上游登錄檔中的儲存庫與您的 Amazon ECR 私有儲存庫同步。如需詳細資訊,請參閱《Amazon ECR 使用者指南》中的同步上游登錄檔。

當您建立快取時,提取快取會自動在私有登錄檔中建立映像儲存庫,並在上游映像發生變更時自動與快取映像同步。

HealthOmics 支援下列上游登錄檔的提取快取:

  • Amazon ECR Public

  • Kubernetes 容器映像登錄檔

  • Quay

  • Docker Hub

  • Microsoft Azure Container Registry

  • GitHub Container Registry

  • GitLab 容器登錄檔

HealthOmics 不支援為上游 Amazon ECR 私有儲存庫提取快取。

使用 Amazon ECR 提取快取的優勢包括:

  1. 您不必手動將容器映像遷移至 Amazon ECR 或同步來自第三方儲存庫的更新。

  2. 工作流程會存取私有儲存庫中的同步容器映像,這比在執行時間從公有登錄檔下載內容更可靠。

  3. 由於 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 主控台執行下列步驟:

  1. 開啟 Amazon ECR 主控台:https://https://console.aws.amazon.com/ecr

  2. 在左側選單的私有登錄檔下,展開功能和設定。然後選擇提取快取

  3. 提取快取頁面,選擇新增規則

  4. 上游登錄面板中,選擇要與您的私有登錄同步的上游登錄檔,然後選擇下一步

  5. 如果上游登錄檔需要身分驗證,主控台會開啟新頁面,您可以在其中指定包含登入資料的 SageMaker AI 秘密。選擇下一步

  6. 指定命名空間下,在快取命名空間面板中,選擇是否使用特定儲存庫字首或沒有字首來建立私有儲存庫。如果您選擇使用字首,請在快取儲存庫字首中指定字首名稱。

  7. 上游命名空間面板中,選擇使用特定儲存庫字首或無字首從上游儲存庫提取。如果您選擇使用字首,請在上游儲存庫字首中指定字首名稱。

    命名空間範例面板會顯示範例提取請求、上游 URL 和所建立快取儲存庫的 URL。

  8. 選擇下一步

  9. 檢閱組態,然後選擇建立以建立規則。

如需詳細資訊,請參閱建立提取快取規則 (AWS 管理主控台)

使用 CLI 建立提取快取規則

使用 Amazon ECR create-pull-through-cache-rule命令來建立提取快取規則。對於需要身分驗證的上游登錄檔,請將登入資料存放在 Secrets Manager 秘密中。

以下各節提供每個支援的上游登錄檔的範例。

下列範例會為 Amazon ECR Public 登錄檔建立提取快取規則。其會指定 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 Resource Name (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 Container Registry 的提取快取規則。其會指定 github 的儲存庫字首,這會導致使用提取快取規則建立的每個儲存庫具有 github/upstream-repository-name 的命名規則。您必須指定秘密包含 GitHub Container Registry 憑證的完整 Amazon Resource Name (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 Container Registry 的提取快取規則。其會指定 azure 的儲存庫字首,這會導致使用提取快取規則建立的每個儲存庫具有 azure/upstream-repository-name 的命名規則。您必須指定秘密包含 Microsoft Azure Container Registry 憑證的完整 Amazon Resource Name (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 Container Registry 的提取快取規則。其會指定 gitlab 的儲存庫字首,這會導致使用提取快取規則建立的每個儲存庫具有 gitlab/upstream-repository-name 的命名規則。您必須指定包含 GitLab Container Registry 登入資料之秘密的完整 Amazon Resource Name (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 服務建立具有指定提取快取字首的儲存庫 (以及啟動上游提取至這些儲存庫)。

  1. 從 Amazon ECR 主控台開啟左側選單,在私有登錄檔下展開登錄檔許可,然後選擇產生陳述式

  2. 在右上角,選擇 JSON。輸入類似下列的政策:

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

儲存庫建立範本

若要在 HealthOmics 中使用提取快取,Amazon ECR 儲存庫必須具有儲存庫建立範本。當您或 Amazon ECR 為上游登錄檔建立私有儲存庫時,範本會定義 的組態設定。

每個範本都包含儲存庫命名空間字首,Amazon ECR 會使用此字首將新儲存庫與特定範本比對。範本會指定所有儲存庫設定的組態,包括資源型存取政策、標籤不可變性、加密和生命週期政策。

如需詳細資訊,請參閱《Amazon Elastic Container Registry 使用者指南》中的儲存庫建立範本

如何建立儲存庫建立範本:

  1. 從 Amazon ECR 主控台開啟左側選單,在私有登錄檔下展開功能和設定。然後選擇儲存庫建立範本

  2. 選擇建立範本

  3. 範本詳細資訊中,選擇提取快取

  4. 選擇將此範本套用至特定字首,還是套用至不符合其他範本的所有儲存庫。

    如果您選擇特定字首,請在字首中輸入命名空間字首值。您在建立 PTC 規則時指定此字首。

  5. 選擇下一步

  6. 新增儲存庫建立組態頁面中,輸入儲存庫許可。使用其中一個範例政策陳述式,或輸入類似下列範例的範例:

    JSON
    { "Version":"2012-10-17", "Statement": [ { "Sid": "PTCRepoCreationTemplate", "Effect": "Allow", "Principal": { "Service": "omics.amazonaws.com" }, "Action": [ "ecr:BatchGetImage", "ecr:GetDownloadUrlForLayer" ], "Resource": "*" } ] }
  7. 或者,您可以新增儲存庫設定,例如生命週期政策和標籤。Amazon ECR 會將這些規則套用至為提取快取而建立且使用指定字首的所有容器映像。

  8. 選擇下一步

  9. 檢閱組態,然後選擇下一步

建立工作流程

當您建立新的工作流程或工作流程版本時,請檢閱登錄檔映射並視需要更新。如需詳細資訊,請參閱建立私有工作流程

登錄檔映射

您可以定義登錄檔映射,以便在私有 Amazon ECR 登錄檔中的字首與上游登錄檔名稱之間進行映射。

如需 Amazon ECR 登錄檔映射的詳細資訊,請參閱在 Amazon 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 映像映射的詳細資訊,請參閱在 Amazon 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 .
  • 進入點和 shell

    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_TASK

此變數是目前任務的名稱。

AWS_WORKFLOW_TASK_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 支援的容器映像大小上限,請參閱 。