翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# プライベートワークフローのコンテナイメージ
HealthOmics は、Amazon ECR プライベートリポジトリでホストされているコンテナイメージをサポートしています。コンテナイメージを作成し、プライベートリポジトリにアップロードできます。Amazon ECR プライベートレジストリをプルスルーキャッシュとして使用して、アップストリームレジストリのコンテンツを同期することもできます。
Amazon ECR リポジトリは、サービスを呼び出すアカウントと同じ AWS リージョンに存在する必要があります。ソースイメージリポジトリに適切なアクセス許可がある限り、別の がコンテナイメージを所有 AWS アカウント できます。詳細については、「[クロスアカウント Amazon ECR アクセスのポリシー](permissions-ecr.md#permissions-cross-account)」を参照してください。
実行を開始する前にアクセスを検証できるように、Amazon ECR コンテナイメージ URIs をワークフローのパラメータとして定義することをお勧めします。また、リージョンパラメータを変更することで、新しいリージョンでワークフローを簡単に実行できます。
**注記**
HealthOmics は ARM コンテナをサポートしておらず、パブリックリポジトリへのアクセスもサポートしていません。
HealthOmics が Amazon ECR にアクセスするための IAM アクセス許可の設定については、「」を参照してください[HealthOmics リソースのアクセス許可](permissions-resource.md)。
**Topics**
+ [サードパーティーのコンテナレジストリとの同期](#ecr-pull-through)
+ [Amazon ECR コンテナイメージの一般的な考慮事項](#ecr-considerations)
+ [HealthOmics ワークフローの環境変数](#ecr-env-vars)
+ [Amazon ECR コンテナイメージでの Java の使用](#ecr-java-considerations)
+ [Amazon ECR コンテナイメージにタスク入力を追加する](#ecr-tasks)
## サードパーティーのコンテナレジストリとの同期
Amazon ECR プルスルーキャッシュルールを使用して、サポートされているアップストリームレジストリ内のリポジトリを Amazon ECR プライベートリポジトリと同期できます。詳細については、*「Amazon ECR ユーザーガイド*[」の「アップストリームレジストリの同期](https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache.html)」を参照してください。
プルスルーキャッシュは、キャッシュの作成時にプライベートレジストリにイメージリポジトリを自動的に作成し、アップストリームイメージに変更があるとキャッシュされたイメージと自動的に同期します。
HealthOmics は、次のアップストリームレジストリのプルスルーキャッシュをサポートしています。
+ Amazon ECR Public
+ Kubernetes コンテナイメージレジストリ
+ Quay
+ Docker Hub
+ Microsoft Azure コンテナレジストリ
+ GitHub コンテナレジストリ
+ GitLab コンテナレジストリ
HealthOmics は、アップストリーム Amazon ECR プライベートリポジトリのプルスルーキャッシュをサポートしていません。
Amazon ECR プルスルーキャッシュを使用する利点は次のとおりです。
1. コンテナイメージを Amazon ECR に手動で移行したり、サードパーティーリポジトリから更新を同期したりする必要はありません。
1. ワークフローは、プライベートリポジトリ内の同期されたコンテナイメージにアクセスします。これは、パブリックレジストリから実行時にコンテンツをダウンロードするよりも信頼性が高くなります。
1. Amazon ECR プルスルーキャッシュは予測可能な URI 構造を使用するため、HealthOmics サービスは Amazon ECR プライベート URI をアップストリームレジストリ URI に自動的にマッピングできます。ワークフロー定義の URI 値を更新して置き換える必要はありません。
**Topics**
+ [プルスルーキャッシュの設定](#ecr-pull-through-configure)
+ [レジストリマッピング](#ecr-pull-through-registry-mapping)
+ [イメージマッピング](#ecr-pull-through-mapping-format)
### プルスルーキャッシュの設定
Amazon ECR は、各リージョン AWS アカウント の のレジストリを提供します。ワークフローを実行する予定のリージョンと同じリージョンに Amazon ECR 設定を作成してください。
以下のセクションでは、プルスルーキャッシュの設定タスクについて説明します。
**Topics**
+ [プルスルーキャッシュルールを作成する](#create-ecr-ptc)
+ [アップストリームレジストリのレジストリアクセス許可](#reg-ecr-ptc)
+ [リポジトリ作成テンプレート](#repo-create-templates-ptc)
+ [ワークフローを作成します](#reg-mapping-ecr-ptc)
#### プルスルーキャッシュルールを作成する
キャッシュするイメージを持つアップストリームレジストリごとに Amazon ECR プルスルーキャッシュルールを作成します。ルールは、アップストリームレジストリと Amazon ECR プライベートリポジトリ間のマッピングを指定します。
認証を必要とするアップストリームレジストリの場合は、AWS Secrets Manager を使用して認証情報を指定します。
**注記**
アクティブな実行がプライベートリポジトリを使用している間は、プルスルーキャッシュルールを変更しないでください。実行が失敗するか、より重要なことに、予期しないイメージを使用してパイプラインが発生する可能性があります。
詳細については、*「Amazon Elastic Container Registry ユーザーガイド*」の[「プルスルーキャッシュルールの作成](https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache-creating-rule.html)」を参照してください。
##### コンソールを使用してプルスルーキャッシュルールを作成する
プルスルーキャッシュを設定するには、Amazon ECR コンソールを使用して以下の手順を実行します。
1. Amazon ECR コンソールを開きます: https://console.aws.amazon.com/ecr
1. 左側のメニューから、**プライベートレジストリ**で**機能と設定**を展開し、**プルスルーキャッシュ**を選択します。
1. **プルスルーキャッシュ**ページから、**ルールの追加**を選択します。
1. **アップストリームレジストリ**パネルで、プライベートレジストリと同期するアップストリームレジストリを選択し、次**へ**を選択します。
1. アップストリームレジストリで認証が必要な場合、コンソールは認証情報を含む SageMaker AI シークレットを指定する新しいページを開きます。[**次へ**] を選択します。
1. **名前空間の指定** の**キャッシュ名前空間**パネルで、特定のリポジトリプレフィックスを使用するか、プレフィックスなしでプライベートリポジトリを作成するかを選択します。プレフィックスを使用する場合は、**キャッシュリポジトリ**プレフィックスでプレフィックス名を指定します。
1. **アップストリーム名前空間**パネルで、特定のリポジトリプレフィックスを使用してアップストリームリポジトリからプルするか、プレフィックスなしでプルするかを選択します。プレフィックスを使用する場合は、**アップストリームリポジトリ**プレフィックスでプレフィックス名を指定します。
**名前空間サンプル**パネルには、プルリクエストの例、アップストリーム URL、作成されたキャッシュリポジトリの URL が表示されます。
1. [**次へ**] を選択します。
1. 設定を確認し、**作成**を選択してルールを作成します。
詳細については、[「プルスルーキャッシュルールを作成する (AWS マネジメントコンソール)](https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache-creating-rule.html#pull-through-cache-creating-rule-console)」を参照してください。
##### CLI を使用してプルスルーキャッシュルールを作成する
Amazon ECR **create-pull-through-cache-rule** コマンドを使用して、プルスルーキャッシュルールを作成します。認証を必要とするアップストリームレジストリの場合は、認証情報を Secrets Manager シークレットに保存します。
以下のセクションでは、サポートされている各アップストリームレジストリの例を示します。
##### Amazon ECR Public の場合
次の例では、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` を指定します。この結果、プルスルーキャッシュルールを使用して作成された各リポジトリは命名スキーム `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` を指定します。この結果、プルスルーキャッシュルールを使用して作成された各リポジトリは命名スキーム `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` を指定します。この結果、プルスルーキャッシュルールを使用して作成された各リポジトリは命名スキーム `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` を指定します。この結果、プルスルーキャッシュルールを使用して作成された各リポジトリは命名スキーム `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 コンテナレジストリの場合
次の例では、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` を指定します。この結果、プルスルーキャッシュルールを使用して作成された各リポジトリは命名スキーム `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)](https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache-creating-rule.html#pull-through-cache-creating-rule-cli) の作成」を参照してください。
**get-run-task** CLI コマンドを使用して、特定のタスクに使用されるコンテナイメージに関する情報を取得できます。
```
aws omics get-run-task --id 1234567 --task-id
```
出力には、コンテナイメージに関する以下の情報が含まれます。
```
"imageDetails": {
"image": "string",
"imageDigest": "string",
"sourceImage": "string",
...
}
```
#### アップストリームレジストリのレジストリアクセス許可
レジストリアクセス許可を使用して、HealthOmics がプルスルーキャッシュを使用し、コンテナイメージを Amazon ECR プライベートレジストリにプルできるようにします。実行で使用されるコンテナを提供する Amazon ECR レジストリポリシーをレジストリに追加します。
次のポリシーは、HealthOmics サービスが指定されたプルスルーキャッシュプレフィックス (複数可) を使用してリポジトリを作成し、これらのリポジトリへのアップストリームプルを開始するアクセス許可を付与します。
1. Amazon ECR コンソールから、左側のメニューの**プライベートレジストリ**で**レジストリのアクセス許可**を展開し、**ステートメントの生成**を選択します。
1. 右上で、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 ユーザーガイド」の「リポジトリ作成テンプレート](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-creation-templates.html)」を参照してください。 **
リポジトリ作成テンプレートを作成する方法:
1. Amazon ECR コンソールから、左側のメニューの**プライベートレジストリ**で**機能と設定**を展開し、**リポジトリ作成テンプレート**を選択します。
1. **[テンプレートを作成]** をクリックします。
1. **テンプレートの詳細**で、**プルスルーキャッシュ**を選択します。
1. このテンプレートを特定のプレフィックスに適用するか、別のテンプレートと一致しないすべてのリポジトリに適用するかを選択します。
**特定のプレフィックス**を選択した場合は、**プレフィックス**に名前空間プレフィックス値を入力します。PTC ルールの作成時にこのプレフィックスを指定しました。
1. [**次へ**] を選択します。
1. **リポジトリ作成設定の追加**ページで、**リポジトリのアクセス許可**を入力します。サンプルポリシーステートメントのいずれかを使用するか、次の例のようなものを入力します。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "PTCRepoCreationTemplate",
"Effect": "Allow",
"Principal": {
"Service": "omics.amazonaws.com"
},
"Action": [
"ecr:BatchGetImage",
"ecr:GetDownloadUrlForLayer"
],
"Resource": "*"
}
]
}
```
------
1. 必要に応じて、ライフサイクルポリシーやタグなどのリポジトリ設定を追加できます。Amazon ECR は、指定されたプレフィックスを使用するプルスルーキャッシュ用に作成されたすべてのコンテナイメージにこれらのルールを適用します。
1. [**次へ**] を選択します。
1. 設定を確認し、**次へ**を選択します。
#### ワークフローを作成します
新しいワークフローまたはワークフローバージョンを作成するときは、レジストリマッピングを確認し、必要に応じて更新します。詳細については、「[プライベートワークフローを作成する](create-private-workflow.md)」を参照してください。
### レジストリマッピング
プライベート Amazon ECR レジストリのプレフィックスとアップストリームレジストリ名の間でマッピングするレジストリマッピングを定義します。
Amazon ECR レジストリマッピングの詳細については、[「Amazon ECR でのプルスルーキャッシュルールの作成](https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache-creating-rule.html)」を参照してください。
次の例は、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 でのプルスルーキャッシュルールの作成](https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache-creating-rule.html)」を参照してください。
次の例は、プライベート 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\$164 コンテナをサポートしています。ローカルマシンが Apple Mac などの ARM ベースである場合は、次のようなコマンドを使用して x86\$164 コンテナイメージを構築します。
```
docker build --platform amd64 -t my_tool:latest .
```
+ エントリポイントとシェル
HealthOmics ワークフローエンジンは、ワークフロータスクで使用されるコンテナイメージへのコマンドオーバーライドとして bash スクリプトを挿入します。したがって、コンテナイメージは、bash シェルがデフォルトになるように、指定された ENTRYPOINT なしで構築する必要があります。
+ マウントされたパス
共有ファイルシステムは /tmp でコンテナタスクにマウントされます。この場所でコンテナイメージに組み込まれているデータまたはツールはすべて上書きされます。
ワークフロー定義は、/mnt/workflow の読み取り専用マウントを介してタスクで使用できます。
+ イメージのサイズ
コンテナイメージの最大サイズ[HealthOmics ワークフローの固定サイズクォータ](fixed-quotas.md#fixed-quotas-workflows)については、「」を参照してください。
## HealthOmics ワークフローの環境変数
HealthOmics は、コンテナで実行されているワークフローに関する情報を含む環境変数を提供します。これらの変数の値は、ワークフロータスクのロジックで使用できます。
すべての HealthOmics ワークフロー変数は`AWS_WORKFLOW_`、 プレフィックスで始まります。このプレフィックスは、保護された環境変数プレフィックスです。ワークフローコンテナの独自の変数にこのプレフィックスを使用しないでください。
HealthOmics には、次のワークフロー環境変数が用意されています。
**AWS\$1REGION**
この変数は、コンテナが実行されているリージョンです。
**AWS\$1WORKFLOW\$1RUN**
この変数は、現在の実行の名前です。
**AWS\$1WORKFLOW\$1RUN\$1ID**
この変数は、現在の実行の実行識別子です。
**AWS\$1WORKFLOW\$1RUN\$1UUID**
この変数は、現在の実行の実行 UUID です。
**AWS\$1WORKFLOW\$1TASK**
この変数は現在のタスクの名前です。
**AWS\$1WORKFLOW\$1TASK\$1ID**
この変数は、現在のタスクのタスク識別子です。
**AWS\$1WORKFLOW\$1TASK\$1UUID**
この変数は、現在のタスクのタスク 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 の使用
ワークフロータスクで GATK などの Java アプリケーションを使用する場合は、コンテナの次のメモリ要件を考慮してください。
+ Java アプリケーションはスタックメモリとヒープメモリを使用します。デフォルトでは、最大ヒープメモリはコンテナで使用可能なメモリの合計に対する割合です。このデフォルトは特定の JVM ディストリビューションと JVM バージョンに依存するため、JVM の関連ドキュメントを参照するか、Java コマンドラインオプション (「-Xmx」など) を使用してヒープメモリの最大数を明示的に設定してください。
+ JVM スタックにもメモリが必要なため、最大ヒープメモリをコンテナのメモリ割り当ての 100% に設定しないでください。メモリは、JVM ガベージコレクターおよびコンテナで実行されているその他のオペレーティングシステムプロセスにも必要です。
+ GATK などの一部の Java アプリケーションでは、ネイティブメソッド呼び出しや、メモリマッピングファイルなどのその他の最適化を使用できます。これらの手法には、JVM 最大ヒープパラメータによって制御されない「オフヒープ」で実行されるメモリ割り当てが必要です。
Java アプリケーションがオフヒープメモリを割り当てることを知っている (または疑っている) 場合は、タスクメモリ割り当てにオフヒープメモリ要件が含まれていることを確認してください。
これらのオフヒープ割り当てによってコンテナのメモリが不足した場合、JVM はこのメモリを制御しないため、通常 Java **OutOfMemory** エラーは表示されません。
## Amazon ECR コンテナイメージにタスク入力を追加する
ワークフロータスクの実行に必要なすべての実行可能ファイル、ライブラリ、スクリプトを、タスクの実行に使用される Amazon ECR イメージに追加します。
ベストプラクティスは、タスクコンテナイメージの外部にあるスクリプト、バイナリ、ライブラリを使用しないことです。これは、`nf-core`ワークフローパッケージの一部として`bin`ディレクトリを使用するワークフローを使用する場合に特に重要です。このディレクトリはワークフロータスクで使用できますが、読み取り専用ディレクトリとしてマウントされます。このディレクトリに必要なリソースはタスクイメージにコピーし、実行時またはタスクに使用されるコンテナイメージの構築時に使用できるようにする必要があります。
HealthOmics がサポートするコンテナイメージの最大サイズ[HealthOmics ワークフローの固定サイズクォータ](fixed-quotas.md#fixed-quotas-workflows)については、「」を参照してください。