翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# プルスルーキャッシュでサポートされているサードパーティーレジストリの使用
Amazon ECR プルスルーキャッシュルールを使用して、サポートされているアップストリームレジストリ内のリポジトリを Amazon ECR プライベートリポジトリと同期できます。詳細については、*Amazon Elastic Container Registry *[ユーザーガイドの「アップストリームレジストリの同期](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 プライベートリポジトリにコピーします。詳細については、「[プルスルーキャッシュでサポートされていないサードパーティーレジストリの使用](containers-non-ptc-registries.md)」を参照してください。
Amazon ECR プルスルーキャッシュを使用する利点は次のとおりです。
1. コンテナイメージを Amazon ECR に手動で移行したり、サードパーティーリポジトリから更新を同期したりする必要はありません。
1. ワークフローは、プライベートリポジトリ内の同期されたコンテナイメージにアクセスします。これは、パブリックレジストリから実行時にコンテンツをダウンロードするよりも信頼性が高くなります。
1. Amazon ECR プルスルーキャッシュは予測可能な URI 構造を使用するため、アップストリームイメージ URIs をワークフロー定義に保持し、それらを解決するコンテナレジストリマップをキャッシュリポジトリに追加できます。詳細については、「[ステップ 4: コンテナレジストリマップを追加する (ワークフローがアップストリーム URIs を使用している場合)](#ecr-ptc-registry-map)」を参照してください。
**Topics**
+ [前提条件](#ecr-ptc-prerequisites)
+ [プルスルーキャッシュの設定](#ecr-pull-through-configure)
+ [設定の再実行](#rerun-ecr-ptc)
+ [プルスルーキャッシュのトラブルシューティング](#ecr-ptc-troubleshooting)
## 前提条件
アップストリームレジストリが認証を必要とする場合、 AWS Secrets Manager シークレットはプルスルーキャッシュルールと同じ AWS アカウント およびリージョンにある必要があります。ルールを作成するときは、Secrets Manager が返すのとまったく同じように`--credential-arn`シークレットの ARN を渡します。これには、Secrets Manager が名前に追加するサフィックスが含まれます。Secrets Manager **create-secret**と **describe-secret** レスポンスの両方が返します。このトピックARNs の例は、シークレット名を省略したものです。
| アップストリームレジストリ | レジストリ URL | Secrets Manager シークレットが必要です |
| --- | --- | --- |
| Amazon ECR Public | `public.ecr.aws` | いいえ |
| Kubernetes コンテナイメージレジストリ | `registry.k8s.io` | いいえ |
| Quay | `quay.io` | いいえ |
| Docker Hub | `registry-1.docker.io` | あり |
| Microsoft Azure コンテナレジストリ | `{{registry-name}}.azurecr.io` | あり |
| GitHub コンテナレジストリ | `ghcr.io` | あり |
| GitLab コンテナレジストリ | `registry.gitlab.com` | あり |
シークレット名は で始まる必要があります`ecr-pullthroughcache/`。その他の要件については、[「Amazon Elastic Container Registry ユーザーガイド」の「 AWS Secrets Manager シークレットにアップストリームリポジトリ認証情報を保存する](https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache-creating-secret.html)」を参照してください。 **
## プルスルーキャッシュの設定
Amazon ECR は、各リージョン AWS アカウント の のレジストリを提供します。ワークフローを実行する予定のリージョンと同じリージョンに Amazon ECR 設定を作成してください。
次の設定タスクを順番に実行します。ステップ 4 は、ワークフロー定義がアップストリームイメージ URIs を使用している場合にのみ適用されます。
**Topics**
+ [ステップ 1: プルスルーキャッシュルールを作成する](#create-ecr-ptc)
+ [ステップ 2: アップストリームレジストリのアクセス許可を設定する](#reg-ecr-ptc)
+ [ステップ 3: リポジトリテンプレートを作成する](#repo-create-templates-ptc)
+ [ステップ 4: コンテナレジストリマップを追加する (ワークフローがアップストリーム URIs を使用している場合)](#ecr-ptc-registry-map)
+ [ステップ 5: プルスルーキャッシュ設定を検証する](#verify-ecr-ptc)
### ステップ 1: プルスルーキャッシュルールを作成する
キャッシュするイメージを持つアップストリームレジストリごとに 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: アップストリームレジストリの選択**
1. [Amazon ECR コンソール](https://console.aws.amazon.com/ecr/)を開きます。
1. ナビゲーションペインの**プライベートレジストリ**で、**機能と設定**を展開し、プル**スルーキャッシュ**を選択します。
1. **プルスルーキャッシュ**ページで、**ルールの追加**を選択します。
1. **アップストリームレジストリ**パネルで、プライベートレジストリと同期するアップストリームレジストリを選択し、**次へ**を選択します。
1. アップストリームレジストリで認証が必要な場合は、次のページで、認証情報を含む Secrets Manager シークレットを指定します。[**次へ**] を選択します。
**パート 2: 名前空間の指定とルールの作成**
1. **名前空間の指定** の**キャッシュ名前空間**パネルで、特定のリポジトリプレフィックスを使用するか、プレフィックスなしでプライベートリポジトリを作成するかを選択します。プレフィックスを使用する場合は、**キャッシュリポジトリ**プレフィックスでプレフィックス名を指定します。
1. **アップストリーム名前空間**パネルで、特定のリポジトリプレフィックスを使用してアップストリームリポジトリからプルするか、プレフィックスなしでプルするかを選択します。プレフィックスを使用する場合は、**アップストリームリポジトリ**プレフィックスでプレフィックス名を指定します。
**名前空間サンプル**パネルには、プルリクエストの例、アップストリーム URL、作成されたキャッシュリポジトリの URL が表示されます。
1. [**次へ**] を選択します。
1. 設定を確認し、**作成**を選択してルールを作成します。
#### を使用したプルスルーキャッシュルールの作成 AWS 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 container image registry ]
次の例では、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 Container Registry ]
次の例では、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 Container Registry ]
次の例では、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 Container Registry ]
次の例では、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}}
```
------
**get-run-task** AWS CLI コマンドを使用して、特定のタスクに使用されるコンテナイメージに関する情報を取得できます。
```
aws omics get-run-task --id {{run-id}} --task-id {{task-id}}
```
出力には、コンテナイメージに関する次の情報が含まれます。
```
"imageDetails": {
"image": "string",
"imageDigest": "string",
"sourceImage": "string",
...
}
```
### ステップ 2: アップストリームレジストリのアクセス許可を設定する
レジストリアクセス許可を使用して、HealthOmics がプルスルーキャッシュを使用し、コンテナイメージを Amazon ECR プライベートレジストリにプルできるようにします。実行で使用されるコンテナを提供する Amazon ECR レジストリポリシーをレジストリに追加します。
次のポリシーは、HealthOmics サービスが指定されたプルスルーキャッシュプレフィックスを持つリポジトリを作成し、これらのリポジトリへのアップストリームプルを開始するアクセス許可を付与します。
レジストリポリシーは独自のリージョンとアカウントにのみ適用されるため、 が作成したすべてのキャッシュリポジトリプレフィックス`Resource`をカバーし、各リポジトリ ARN AWS アカウント のリージョンと を設定対象のレジストリに設定します。
1. [Amazon ECR コンソール](https://console.aws.amazon.com/ecr/)を開きます。
1. ナビゲーションペインの**プライベートレジストリ**で、**レジストリのアクセス許可**を展開し、**ステートメントの生成**を選択します。
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/*"
]
}
]
}
```
------
1. ポリシーを保存します。
AWS CLI 代わりに でポリシーをアタッチするには、ポリシーをファイルに保存し、Amazon ECR **put-registry-policy** コマンドを使用します。
```
aws ecr put-registry-policy \
--policy-text file://{{registry-policy-file}}.json \
--region {{region}}
```
**重要**
**put-registry-policy** はレジストリポリシー全体を置き換えます。レジストリに既にポリシーがある場合は、 で取得し**get-registry-policy**、HealthOmics ステートメントを追加して、組み合わせたポリシーを元に戻します。
Amazon ECR プルスルーキャッシュのポリシーの詳細については、「」を参照してください[Amazon ECR プルスルーキャッシュのポリシー](permissions-ecr.md#permissions-ecr-ptc)。
### ステップ 3: リポジトリテンプレートを作成する
HealthOmics でプルスルーキャッシュを使用するには、Amazon ECR リポジトリにリポジトリ作成テンプレートが必要です。テンプレートは、ユーザーまたは Amazon ECR がアップストリームレジストリのプライベートリポジトリを作成するときの設定を定義します。
各テンプレートには、Amazon ECR が新しいリポジトリを特定のテンプレートに一致させるために使用するリポジトリ名前空間プレフィックスが含まれています。テンプレートは、リソースベースのアクセスポリシー、タグのイミュータビリティ、暗号化、ライフサイクルポリシーなど、すべてのリポジトリ設定の構成を指定します。
詳細については、[「Amazon Elastic Container Registry ユーザーガイド」の「リポジトリ作成テンプレート](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-creation-templates.html)」を参照してください。 **
**注記**
プレフィックスを使用する最初の実行前にテンプレートを作成します。プレフィックスに独自のテンプレートがなく、`ROOT`テンプレートもないため、HealthOmics はキャッシュされたイメージをプルできません。タグのミュータビリティを のままにしておき`MUTABLE`、アップストリームタグが変更されたときに Amazon ECR がキャッシュされたイメージを更新できるようにします。既に存在するリポジトリについては、「」を参照してください[テンプレートの前に作成されたリポジトリの更新](#ecr-ptc-troubleshoot-template-late)。
リポジトリ作成テンプレートを作成するには、Amazon ECR コンソールを使用して以下の手順を実行します。
**パート 1: テンプレートの定義**
1. [Amazon ECR コンソール](https://console.aws.amazon.com/ecr/)を開きます。
1. ナビゲーションペインの**プライベートレジストリ**で、**機能と設定**を展開し、**リポジトリ作成テンプレート**を選択します。
1. **[テンプレートを作成]** をクリックします。
1. **テンプレートの詳細**で、**プルスルーキャッシュ**を選択します。
1. このテンプレートを特定のプレフィックスに適用するか、別のテンプレートと一致しないすべてのリポジトリに適用するかを選択します。
**特定のプレフィックス**を選択した場合は、**プレフィックス**に名前空間プレフィックス値を入力します。このプレフィックスは、プルスルーキャッシュルールの作成時に指定しました。
1. [**次へ**] を選択します。
**パート 2: リポジトリ作成設定の追加**
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. 設定を確認し、**作成**を選択してテンプレートを作成します。
AWS CLI 代わりに を使用してテンプレートを作成するには、前述の手順のリポジトリポリシーを ファイルに保存し、プルスルーキャッシュルールのキャッシュリポジトリプレフィックスに を`--prefix`設定した Amazon ECR **create-repository-creation-template** コマンドを使用します。説明はオプションです。
```
aws ecr create-repository-creation-template \
--prefix {{ecr-repository-prefix}} \
--applied-for PULL_THROUGH_CACHE \
--repository-policy file://{{repository-policy-file}}.json \
--image-tag-mutability MUTABLE \
--description "{{description}}" \
--region {{region}}
```
プレフィックスのテンプレートが既に存在する場合、 は TemplateAlreadyExistsException で**create-repository-creation-template**失敗します。代わりに既存のテンプレートを更新します。
```
aws ecr update-repository-creation-template \
--prefix {{ecr-repository-prefix}} \
--applied-for PULL_THROUGH_CACHE \
--repository-policy file://{{repository-policy-file}}.json \
--image-tag-mutability MUTABLE \
--region {{region}}
```
**重要**
**update-repository-creation-template** は、渡した各値を置き換えるため、既存のリスト`--applied-for`とポリシーをマージするのではなく`--repository-policy`、上書きします。で現在のテンプレートを取得し**describe-repository-creation-templates**、変更をマージして、完全な値を渡します。
Amazon ECR は設定されていますが、HealthOmics の設定は完了していません。ワークフロー定義でアップストリームイメージ URIs、コンテナレジストリマップなしで [ステップ 4: コンテナレジストリマップを追加する (ワークフローがアップストリーム URIs を使用している場合)](#ecr-ptc-registry-map): に進み、起動後に実行が失敗します。それ以外の場合は、「[ステップ 5: プルスルーキャッシュ設定を検証する](#verify-ecr-ptc)」に進みます。
### ステップ 4: コンテナレジストリマップを追加する (ワークフローがアップストリーム URIs を使用している場合)
ワークフロー定義のイメージ URIs によって、コンテナレジストリマップが必要かどうかが決まります。
| ワークフロー定義のイメージ URIs | レジストリマップ |
| --- | --- |
| 形式のアップストリーム URIs `{{upstream-registry-url}}/{{upstream-repository-name}}:{{tag}}` | マップを追加します。このマップは、どのキャッシュリポジトリプレフィックスがどのアップストリームレジストリに属するかを HealthOmics に指示します。これは、HealthOmics がプルスルーキャッシュルールを読み取らないためです。 |
| 形式のキャッシュリポジトリの Amazon ECR プライベート URIs `{{account-id}}.dkr.ecr.{{region}}.amazonaws.com/{{ecr-repository-prefix}}/{{upstream-repository-name}}:{{tag}}` | マップは必要ありません。HealthOmics は、指定された各 URI を使用します。 |
レジストリホストなしで書き込まれるイメージ名は Docker Hub の短縮名であり、アップストリーム URI としてカウントされ、マップが必要です。
定義で両方の種類の URI を使用している場合は、アップストリーム URIs を使用するイメージのマップを追加します。
**重要**
アップストリーム URIs、マップが欠落しているか、イメージのアップストリームレジストリのマッピングがない場合でも、 は`StartRun`成功します。HealthOmics は、それを使用するタスクを作成するときに各イメージを検証するため、起動後に実行が失敗します。どちらの場合も、失敗の理由 INVALID\_ECR\_IMAGE\_URI が指定され、実行のステータスメッセージによって区別されます。イメージを存在しないキャッシュリポジトリに解決するマッピングは、代わりに ECR\_REPOSITORY\_NOT\_FOUND を提供します。
マッピングでプルスルーキャッシュルールをミラーリングする: ルールのアップストリームレジストリ URL、`ecrRepositoryPrefix`キャッシュリポジトリプレフィックス、およびルールが使用している場合はアップ`upstreamRepositoryPrefix`ストリームリポジトリプレフィックス`upstreamRegistryUrl`に設定します。
キャッシュリポジトリがワークフロー AWS アカウント とは異なる にある場合は、 `ecrAccountId`をキャッシュリポジトリを所有するアカウントに設定し、「」で説明されているクロスアカウントポリシーを追加します[クロスアカウント Amazon ECR アクセスのポリシー](permissions-ecr.md#permissions-cross-account)。 `ecrAccountId` はデフォルトでワークフローの独自のアカウントになります。
**注記**
Docker Hub の場合、 `upstreamRegistryUrl` を に設定し`registry-1.docker.io`、 の値を指定します[前提条件](#ecr-ptc-prerequisites)。HealthOmics は `registry-1.docker.io`と を同じホスト`docker.io`として扱うため、1 つのマッピングは で記述されたイメージ URIs もカバーします`docker.io`。
HealthOmics はマッピングと一致する前に短い Docker Hub 名も展開します。 `ubuntu:22.04` は になり`docker.io/library/ubuntu:22.04`、 は `myorg/image:tag`になります`docker.io/myorg/image:tag`。HealthOmics は、定義内のイメージ名にスラッシュがない`library/`場合にのみ挿入します。拡張名によってキャッシュリポジトリパスも決定されるため、 はプライベートレジストリ`{{ecr-repository-prefix}}/library/ubuntu:22.04`の に`ubuntu:22.04`解決されます。
ワークフローまたはワークフローバージョンを作成するときにマップを指定します。ワークフローに必要なマッピングを決定するマップ形式とルールについては、「」を参照してください[レジストリマッピング](containers-workflow-creation.md#ecr-pull-through-registry-mapping)。イメージマッピングについては、「」を参照してください[イメージマッピング](containers-workflow-creation.md#ecr-pull-through-mapping-format)。マップを追加したら、 に進みます[ステップ 5: プルスルーキャッシュ設定を検証する](#verify-ecr-ptc)。
### ステップ 5: プルスルーキャッシュ設定を検証する
と は常に呼び出し元のアカウントのレジストリ**get-registry-policy****describe-repository-creation-templates**を読み取るため、キャッシュリポジトリを所有するアカウントで**aws ecr**コマンドを実行し、ワークフローを所有するアカウントで**aws omics**コマンドを実行します。両方のワークフローを実行するリージョンを使用します。以下の手順の 3 つのチェックは独立しているため、すべてを実行し、修正に戻る前にすべての問題を解決します。「」で説明されているように、ワークフローまたはワークフローバージョンを作成したら、プロシージャ後のレジストリマップチェックが適用されます[ワークフロー作成時のプライベートコンテナまたはサードパーティーコンテナの追加](containers-workflow-creation.md)。実行の開始も必要になった後のend-to-endのチェック。
1. プルスルーキャッシュルールが存在し、予想されるアップストリームレジストリを指していることを確認します。
```
aws ecr describe-pull-through-cache-rules \
--region {{region}}
```
作成した各ルールには、 `ecrRepositoryPrefix`と が表示されます`upstreamRegistryUrl`。アップストリームリポジトリプレフィックスを設定するルールには も表示され`upstreamRepositoryPrefix`、認証情報を使用するルールには も表示されます`credentialArn`。Amazon ECR は、ルールが設定しない場合、これらの各フィールドを省略します。空の`pullThroughCacheRules`リストは、このリージョンにルールが存在しないことを意味します。[ステップ 1: プルスルーキャッシュルールを作成する](#create-ecr-ptc)に戻ります。
ルールが認証情報を使用している場合は、Amazon ECR がシークレットを読み取ってアップストリームレジストリにサインインできることを確認します。
```
aws ecr validate-pull-through-cache-rule \
--ecr-repository-prefix {{ecr-repository-prefix}} \
--region {{region}}
```
出力には、認証が成功`"isValid": true`したときが含まれ、それ以外の場合は で理由に名前を付けます`failure`。コマンドが PullThroughCacheRuleNotFoundException で失敗した場合、ルールはそのプレフィックスを使用しません。AccessDeniedException は、呼び出し元に アクセス`ecr:ValidatePullThroughCacheRule`許可がないことを意味します。このアクセス許可には、ルールが間違っていることではなく、読み取り専用ポリシーに常に含まれているわけではありません。詳細については、*「Amazon Elastic Container Registry ユーザーガイド*[」の「プルスルーキャッシュルールの検証](https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache-working-validating.html)」を参照してください。
1. レジストリポリシーが HealthOmics にアクセス権を付与していることを確認します。
```
aws ecr get-registry-policy \
--region {{region}}
```
Amazon ECR が JSON エスケープを返す出力`policyText`の値には、 からの ステートメントが含まれ[ステップ 2: アップストリームレジストリのアクセス許可を設定する](#reg-ecr-ptc)、 `ecr:CreateRepository`と `omics.amazonaws.com`の両方を個別に`ecr:BatchImportUpstreamImage`、またはワイルドカードを介して付与し、作成したすべてのキャッシュリポジトリプレフィックスをカバーする必要があります。プレフィックスは、プレフィックスで終わるリポジトリ ARN の後に が続く、リポジトリ ARN の後に`/*`単独で終わる、 `Resource`の など、その下にあるキャッシュ`/*`リポジトリに一致する`Resource`エントリでカバーされます`*`。なしのプレフィックス自体で終わる ARN は`/*`何もカバーしません。キャッシュリポジトリ名には、常にプレフィックスの下にパスがあります。「」で説明されているように、このレジストリ自体 AWS アカウント 以外のリージョンまたは という名前の ARN も対象になりません[ステップ 2: アップストリームレジストリのアクセス許可を設定する](#reg-ecr-ptc)。プレフィックスをカバーするステートメントがない場合、または RegistryPolicyNotFoundException でコマンドが失敗した場合、 [ステップ 2: アップストリームレジストリのアクセス許可を設定する](#reg-ecr-ptc) に戻り、ポリシーを保存したことを確認します。
1. 各キャッシュリポジトリプレフィックスにリポジトリ作成テンプレートが存在することを確認します。作成したすべてのプレフィックスを渡します。
```
aws ecr describe-repository-creation-templates \
--prefixes {{ecr-repository-prefix-1}} {{ecr-repository-prefix-2}} \
--region {{region}}
```
プレフィックスごとに、次の段落で識別される Amazon ECR がキャッシュリポジトリに適用するテンプレートには、 `PULL_THROUGH_CACHE` `appliedFor`と[ステップ 3: リポジトリテンプレートを作成する](#repo-create-templates-ptc)、、 `ecr:BatchGetImage` からの`omics.amazonaws.com`プルアクションを付与`repositoryPolicy`する が必要です`ecr:GetDownloadUrlForLayer`。空でないポリシーでは不十分です。プリンシパルとアクションを確認します。
Amazon ECR は、プレフィックスがリポジトリの最長一致であるテンプレートを適用します。プレフィックスが一致しない場合は`ROOT`テンプレートを適用します。はパスではなく各プレフィックスを正確に`--prefixes`照合するため、フィルタリングされた出力には`ROOT`テンプレートも長いプレフィックスのテンプレートも表示されないため、すべてのテンプレート`--prefixes`を表示するには、 コマンドを なしで実行します。該当するテンプレートが欠落しているか、いずれかの要件に失敗したプレフィックスについては、このステップに戻ります。 `imageTagMutability`は HealthOmics がイメージをプルできるかどうかには影響しませんが、アップストリームタグの移動時にキャッシュされたイメージの Amazon ECR の更新`MUTABLE`を停止する以外のテンプレートは、「」で説明されています[ステップ 3: リポジトリテンプレートを作成する](#repo-create-templates-ptc)。
テンプレートを作成する前にキャッシュリポジトリが存在していた場合は、「」で説明されているように、各リポジトリのリポジトリポリシーも確認してください[テンプレートの前に作成されたリポジトリの更新](#ecr-ptc-troubleshoot-template-late)。
定義でアップストリーム URIs を使用している場合は、 で追加したレジストリマップを確認します[ステップ 4: コンテナレジストリマップを追加する (ワークフローがアップストリーム URIs を使用している場合)](#ecr-ptc-registry-map)。マップは、指定したワークフローまたはワークフローバージョンに属しているため、実行で使用するバージョンを確認します。 として `--workflow-version-name`に渡すバージョン**start-run**、または実行で名前が付けられていない場合はワークフローです。すでに存在する実行の場合、**get-run**出力`workflowVersionName`ではそのバージョンに名前が付けられます。
ワークフローの場合:
```
aws omics get-workflow \
--id {{workflow-id}} \
--region {{region}}
```
ワークフローバージョンの場合:
```
aws omics get-workflow-version \
--workflow-id {{workflow-id}} \
--version-name {{version-name}} \
--region {{region}}
```
出力`containerRegistryMap`の値を確認します。マップがない場合、レスポンスは フィールドを省略します。`status` が であることを確認します`ACTIVE`。まだ の場合は`CREATING`、待機して再試行し、 の場合は`FAILED`、その理由は にあります`statusMessage`。マップを変更することはできません。マップが見つからない場合や間違っている場合は、「」の説明に従って新しいワークフローバージョンを作成します[設定の再実行](#rerun-ecr-ptc)。
実行がキャッシュされたイメージを使用したことをend-to-endで確認するには、キャッシュを使用する実行の結果を読み取ります。失敗した実行を含め、すでに終了した実行は機能しますが、キャンセルされた実行ではイメージが解決されない場合があります。まだイメージがない場合にのみ実行を開始します。
```
aws omics get-run \
--id {{run-id}} \
--region {{region}}
```
出力の `resourceDigests`フィールドは、実行によってレポートされると、コンテナイメージを含め、実行が解決したリソースを記録します。キーがキャッシュリポジトリプレフィックスの下にある Amazon ECR プライベート URI であり、ダイ`sha256`ジェストがその値であるエントリは、実行によってそのイメージがキャッシュに解決されたことを確認します。これは最も迅速なチェックであり、無関係な理由で失敗した実行でも機能します。
成功せずに実行が停止した場合、 `failureReason`と を`statusMessage`一緒に使用して、この設定が関係しているかどうかを知らせます。イメージで失敗した実行ではタスクがまったく作成されない可能性があるため、実行のタスクを確認する前にこれらを確認してください。
+ キャッシュリポジトリプレフィックスの 1 つにあるイメージ URI の ECR\_REPOSITORY\_NOT\_FOUND、ECR\_IMAGE\_NOT\_FOUND、または ECR\_PERMISSION\_ERROR – に進みます[プルスルーキャッシュのトラブルシューティング](#ecr-ptc-troubleshooting)。プレフィックスの 1 つにない URI の理由の 1 つは、キャッシュルールが適用されないため、プルスルーキャッシュの問題ではなく、そのリポジトリの Amazon ECR の問題です。Amazon ECR で自分で管理するリポジトリの場合は、「」で説明されているように、リポジトリポリシーを使用して HealthOmics にアクセス権を付与します[Amazon ECR リポジトリのリソースポリシーを作成する](permissions-ecr.md#permissions-resource-policy)。
+ INVALID\_ECR\_IMAGE\_URI – レジストリマップがないか、イメージのアップストリームレジストリのマッピングがないか、イメージのパスをカバー`upstreamRepositoryPrefix`していないか、イメージ URI が無効です。ステータスメッセージを読んでこれらを区別し、マップを変更する前に URI を確認します。「[ステップ 4: コンテナレジストリマップを追加する (ワークフローがアップストリーム URIs を使用している場合)](#ecr-ptc-registry-map)」を参照してください。
+ プレフィックスの 1 つにあるイメージ URI の CANNOT\_START\_CONTAINER\_ERROR または IMAGE\_VERIFICATION\_FAILURE – イメージはキャッシュリポジトリに到達しましたが、タスクでは使用できませんでした。キャッシュルールを変更または再作成した場合、古いキャッシュされたイメージが原因でこれが発生する可能性があります。「」を参照してください[実行中のキャッシュルールの変更](#ecr-ptc-troubleshoot-rule-change)。それ以外の場合は、キャッシュされたイメージ自体がこの設定ではなく問題であり、それを使用するアップストリームイメージまたはタスクがどこを参照するかです。
+ その他の失敗の理由、またはキャンセルされた実行レポートとしてまったくない – この設定とは無関係な理由で実行が停止しました。実行ステータスおよびその他の失敗の理由については、[実行情報を取得する](getinfo-about-runs.md)「」および「」を参照してください[実行失敗の理由](workflows-run-errors.md)。
すべての実行が をレポートするわけではなく`resourceDigests`、イメージがまだ解決されていない実行にはエントリがありません。フィールドまたはエントリがない場合、または個々のタスクがプルしたイメージを確認する場合は、実行のタスクを一覧表示します。
```
aws omics list-run-tasks \
--id {{run-id}} \
--region {{region}}
```
まだ実行中の空の`items`リストは、HealthOmics がタスクをまだ作成していないことを意味するため、待機して再度一覧表示します。停止した実行では、タスクが作成されなかったことを意味します。失敗した実行については、前述の失敗の理由を説明し、開始前にキャンセルされた実行には確認すべきものがないため、別の実行を使用してください。それ以外の場合は、前述の出力`taskId`から を使用して、いずれかのタスクのイメージの詳細を取得します。
```
aws omics get-run-task \
--id {{run-id}} \
--task-id {{task-id}} \
--region {{region}} \
--query imageDetails
```
では`imageDetails`、 `sourceImage`はワークフロー定義のイメージ URI であり、 `image`はタスクがプルした Amazon ECR プライベート URI です。キャッシュリポジトリプレフィックスの下の`image`値は、「」に示されているプライベート URI 形式で、[ステップ 4: コンテナレジストリマップを追加する (ワークフローがアップストリーム URIs を使用している場合)](#ecr-ptc-registry-map)場合によってはイメージダイジェストが付加された状態で、タスクがプルスルーキャッシュを使用したことを確認します。 は、イメージをまだプルしていないタスクの場合は 、完了済みのタスクの場合は を空に`imageDetails`することができます。イメージの詳細が記録されていないタスクは、実行マニフェストログにも存在しないため、同じ実行の別のタスクを確認します。完了した実行で記録されたタスクがない場合でも、「」で説明されているように、イメージがキャッシュされていることを確認できます[欠落または不完全なレジストリポリシーの解決](#ecr-ptc-troubleshoot-registry-policy)。これにより、特定のタスクがどのイメージをプルしたかではなく設定が確認されます。これは、以前の実行でキャッシュが入力された可能性があるためです。
実行が完了すると、実行マニフェストログはこのイメージ情報を繰り返すため、実行のタスク**get-run-task**ごとに を呼び出す代わりに、一度に実行のタスクを確認できます。各タスクのレコードで、 という名前のフィールド`image`は`sourceImage`ここで`originalImage`対応し、上記と同じ値です。ログの場所については「」を参照し[CloudWatch Logs による HealthOmics のモニタリング](monitoring-cloudwatch-logs.md)、残りのタスクのレコードについては「」を参照してください[実行情報を取得する](getinfo-about-runs.md)。
プルスルーキャッシュを設定したら、設定されたレジストリのコンテナを使用する新しいワークフローまたはワークフローバージョンを作成できます。詳細については、「[ワークフロー作成時のプライベートコンテナまたはサードパーティーコンテナの追加](containers-workflow-creation.md)」を参照してください。
## 設定の再実行
プレフィックスの追加やポリシーの修正など、これらのステップを繰り返すことができます。リソースが既に存在する場合、作成コマンドはゼロ以外の終了コードで失敗します。 **put-registry-policy**は失敗しませんが、「」で説明されているように、レジストリポリシー全体が置き換えられます[ステップ 2: アップストリームレジストリのアクセス許可を設定する](#reg-ecr-ptc)。
+ プルスルーキャッシュルール – PullThroughCacheRuleAlreadyExistsException で**create-pull-through-cache-rule**失敗します。追加するレジストリに認証が必要な場合は、「」の説明に従って、まず Secrets Manager シークレットを作成します[前提条件](#ecr-ptc-prerequisites)。
+ レジストリアクセス許可ポリシー – 「」で説明されているように、新しいキャッシュリポジトリプレフィックスごとに`Resource`エントリを追加します[ステップ 2: アップストリームレジストリのアクセス許可を設定する](#reg-ecr-ptc)。プレフィックスを個別に列挙するポリシーは、新しいものを対象としません。「」の説明に従って**get-registry-policy**、 でカバレッジを確認します[ステップ 5: プルスルーキャッシュ設定を検証する](#verify-ecr-ptc)。
+ リポジトリ作成テンプレート – キャッシュリポジトリプレフィックスを持たないテンプレートを作成し、既存のテンプレートを更新して、既存のプレフィックスを持つプレフィックスを変更します。どちらも「」で説明されています[ステップ 3: リポジトリテンプレートを作成する](#repo-create-templates-ptc)。別のプレフィックスのテンプレートに対して更新を実行すると、そのテンプレートが上書きされます。Amazon ECR が既に作成したリポジトリを最新の状態にするには、「」を参照してください[テンプレートの前に作成されたリポジトリの更新](#ecr-ptc-troubleshoot-template-late)。
+ コンテナレジストリマップ – ワークフローまたはワークフローバージョンを作成するときにマップを指定し、 **update-workflow** と **update-workflow-version**は変更できません。バージョンを作成する前に、完全なマップを準備する必要があります。新しいバージョンは以前のバージョンのマップを継承しないため、ワークフローが必要とするすべてのマッピングをリストします。 **create-workflow-version**はマップだけでなくバージョン全体を使用するため、「」で説明されているように、ワークフロー定義とバージョンの他のパラメータも必要になります[ワークフローバージョンを作成する](workflows-version-create.md)。次に、「」で説明されているように、更新されたマップを使用してバージョンを作成し[ステップ 4: コンテナレジストリマップを追加する (ワークフローがアップストリーム URIs を使用している場合)](#ecr-ptc-registry-map)、そのバージョンに対して実行を開始します。バージョンに名前を付けない実行では、ワークフローのデフォルトバージョンが使用され、作成されたマップが保持されるため、以前と同じ方法で失敗します。詳細については、「[デフォルトのワークフローバージョン](workflows-default-version.md)」を参照してください。
## プルスルーキャッシュのトラブルシューティング
次の設定の問題により、プルスルーキャッシュからコンテナを使用すると、実行が失敗します。ワークフロー定義がアップストリームイメージ URIs「」で説明されているように、レジストリマップから開始します[ステップ 4: コンテナレジストリマップを追加する (ワークフローがアップストリーム URIs を使用している場合)](#ecr-ptc-registry-map)。 その他の実行失敗の理由については、「」を参照してください[実行失敗の理由](workflows-run-errors.md)。
このセクションの**aws ecr**コマンドを と同じアカウントで実行するか[ステップ 5: プルスルーキャッシュ設定を検証する](#verify-ecr-ptc)、 を渡します`--registry-id {{ecr-account-id}}`。リポジトリ名は が**describe-repositories**返すとおりに使用します。キャッシュリポジトリ名はキャッシュリポジトリプレフィックスの後にアップストリームリポジトリパスが続き、Docker Hub の短縮名には で説明されている`library/`セグメントが含まれます[ステップ 4: コンテナレジストリマップを追加する (ワークフローがアップストリーム URIs を使用している場合)](#ecr-ptc-registry-map)。
### 欠落または不完全なレジストリポリシーの解決
**症状** — イメージ URI の実行が失敗し、次のいずれかの失敗理由があります。
+ ECR\_REPOSITORY\_NOT\_FOUND – キャッシュリポジトリがプライベートレジストリに存在しません。
+ ECR\_IMAGE\_NOT\_FOUND – キャッシュリポジトリは存在しますが、イメージはインポートされませんでした。
+ ECR\_PERMISSION\_ERROR – Amazon ECR はアクセスを拒否します。
キャッシュリポジトリがない場合、次のコマンドはプレフィックスのリポジトリを返します。
```
aws ecr describe-repositories \
--region {{region}} \
--query "repositories[?starts_with(repositoryName, '{{ecr-repository-prefix}}/')]"
```
まだプルされていないプレフィックスの空の結果は予期され、それ自体の設定問題ではありません。イメージ URI の実行が失敗した場合、リポジトリが見つからないということは、通常、Amazon ECR が作成できなかったことを意味します。リポジトリが存在する場合は、イメージがリポジトリに到達したかどうかを確認します。
```
aws ecr describe-images \
--repository-name {{cache-repository-name}} \
--image-ids imageTag={{tag}} \
--region {{region}}
```
返されるイメージは、タグがキャッシュされていることを意味します。ImageNotFoundException は、リポジトリが存在するが、そのタグが存在しないことを意味します。RepositoryNotFoundException は、リポジトリ名が間違っているか、プレフィックスをプルしていないことを意味します。を渡します`--image-ids`。渡さないと、コマンドはリポジトリ内のすべてのタグをレポートするため、別のタグの存在は、実行に必要なタグの成功のように見える可能性があります。
**原因** — レジストリポリシーは HealthOmics に必要なものを付与しません。ポリシーがないか、ポリシーにアクションがないか、`Resource`リストがこのキャッシュプレフィックスをカバーしていません。
**解決策** — 「」の説明に従ってレジストリポリシーを追加または修正し[ステップ 2: アップストリームレジストリのアクセス許可を設定する](#reg-ecr-ptc)、「」の説明に従って確認します[ステップ 5: プルスルーキャッシュ設定を検証する](#verify-ecr-ptc)。レジストリポリシーがキャッシュリポジトリプレフィックスを既にカバーしている場合、レジストリポリシーは問題ではありません。リポジトリが存在するがイメージが到着しなかった ECR\_IMAGE\_NOT\_FOUND の場合、アップストリームインポートは失敗しました。「」で説明されているように**validate-pull-through-cache-rule**、 でルールの認証情報を確認します[ステップ 5: プルスルーキャッシュ設定を検証する](#verify-ecr-ptc)。存在するリポジトリの ECR\_PERMISSION\_ERROR の場合は、 に進みます[欠落しているリポジトリ作成テンプレートまたはリポジトリポリシーの解決](#ecr-ptc-troubleshoot-template)。次に、実行を再度開始します。
### 欠落しているリポジトリ作成テンプレートまたはリポジトリポリシーの解決
**症状** — キャッシュリポジトリはインポートされたイメージに存在し、イメージ URI の ECR\_PERMISSION\_ERROR で実行は失敗します。
**原因** - キャッシュリポジトリプレフィックスに一致するリポジトリ作成テンプレートがないか、テンプレートに `PULL_THROUGH_CACHE` が含まれていないか`appliedFor`、テンプレートにリポジトリポリシーがありません。したがって、リポジトリには HealthOmics がそのリポジトリからプルできるようにするポリシーはありません。
**解決策** — の説明に従ってテンプレートを作成または更新します[ステップ 3: リポジトリテンプレートを作成する](#repo-create-templates-ptc)。リポジトリは既に存在するため、「」で説明されているように、ポリシーもリポジトリに適用します[テンプレートの前に作成されたリポジトリの更新](#ecr-ptc-troubleshoot-template-late)。
### テンプレートの前に作成されたリポジトリの更新
**症状** — リポジトリ作成テンプレートを作成または修正し、正しいと**describe-repository-creation-templates**表示し、同じイメージの Amazon ECR アクセスエラーで実行が失敗します。影響を受けるリポジトリで欠落しているポリシーを確認します。
```
aws ecr get-repository-policy \
--repository-name {{cache-repository-name}} \
--region {{region}}
```
`policyText` 値は、テンプレートのリポジトリポリシーが付与するアクション`omics.amazonaws.com`を少なくとも付与する必要があります。リポジトリにポリシーがまったくない場合、コマンドは RepositoryPolicyNotFoundException で失敗します。RepositoryNotFoundException で失敗した場合、リポジトリ名が正しくないか、リポジトリがまだ存在していません。
**原因** — テンプレートは Amazon ECR がリポジトリを作成する場合にのみ適用されるため、テンプレートを追加する前に作成されたリポジトリには HealthOmics のリポジトリポリシーはありません。
**解決策** — 次のいずれかの方法で、既存のリポジトリを最新の状態に保ちます。
**警告**
リポジトリを削除すると、そのリポジトリ内のキャッシュされたイメージもすべて削除され、元に戻すことはできません。実行がリポジトリを使用している間は、リポジトリを削除しないでください。
+ 既存のリポジトリごとにポリシーを直接設定します。テンプレートのリポジトリポリシーを ファイルに保存し、影響を受けるリポジトリごとに次のコマンドを実行します。
```
aws ecr set-repository-policy \
--repository-name {{cache-repository-name}} \
--policy-text file://{{repository-policy-file}}.json \
--region {{region}}
```
+ 影響を受ける各リポジトリを削除します。プルスルーキャッシュは、次回タスクがイメージをプルするときにテンプレートから再作成するので、キャッシュされたイメージは、そのプルが完了するまで使用できません。
```
aws ecr delete-repository \
--repository-name {{cache-repository-name}} \
--force \
--region {{region}}
```
### 実行中のキャッシュルールの変更
**症状** - プルスルーキャッシュルールを変更または再作成すると、影響を受けるリポジトリを既に使用している実行が CANNOT\_START\_CONTAINER\_ERROR または IMAGE\_VERIFICATION\_FAILURE で失敗するか、予期しなかったイメージを使用して完了する可能性があります。
**原因** - キャッシュリポジトリプレフィックスが別のアップストリームリポジトリに解決されるようになりましたが、実行はすでに古いルールが作成したリポジトリからプルされています。
**解決策** - で[ステップ 1: プルスルーキャッシュルールを作成する](#create-ecr-ptc)説明されているように、ルールを変更する前にアクティブな実行が終了するのを待ちます。タスクが実際に使用したイメージを確認するには、「」の説明に従って**get-run-task**出力`imageDetails`を確認します[ステップ 5: プルスルーキャッシュ設定を検証する](#verify-ecr-ptc)。実行で古いキャッシュ済みイメージを使用した場合は、キャッシュリポジトリからそのイメージを削除して、次のプルでアップストリームレジストリからイメージを更新します。