プルスルーキャッシュルールの使用 - Amazon ECR
プルスルーキャッシュを使用するための考慮事項必要な IAM アクセス許可プルスルーキャッシュルールの作成プルスルーキャッシュイメージの使用プルスルーキャッシュルールの削除

プルスルーキャッシュルールの使用

Amazon ECR は、プライベート Amazon ECR レジストリのリモートパブリックレジストリ内のリポジトリのキャッシュをサポートします。Amazon ECR は現在、Amazon ECR パブリックおよび Quay のプルスルーキャッシュルールの作成をサポートしています。外部パブリックレジストリのプルスルーキャッシュが作成されたら、Amazon ECR プライベートレジストリ URI を使用して、その外部パブリックレジストリからイメージをプルするだけで、Amazon ECR はリポジトリを作成し、そのイメージをキャッシュします。キャッシュされたイメージが Amazon ECR プライベートレジストリ URI を使用してプルされると、Amazon ECR はリモートレジストリをチェックしてイメージの新しいバージョンがあるかどうかを確認し、24 時間ごとに 1 回までプライベートレジストリを更新します。

プルスルーキャッシュを使用するための考慮事項

Amazon ECR のプルスルーキャッシュを使用する際には、以下を考慮する必要があります。

  • 次のリージョンでは、プルスルーキャッシュルールの作成はサポートされていません。

    • 中国 (北京) (cn-north-1)

    • 中国 (寧夏) (cn-northwest-1)

    • AWS GovCloud (米国東部) (us-gov-east-1)

    • AWS GovCloud (米国西部) (us-gov-west-1)

  • プルスルーキャッシュを使用してイメージをプルする場合、イメージを最初にプルするときに Amazon ECR FIPS サービスエンドポイントはサポートされません。ただし、Amazon ECR FIPS サービスエンドポイントは、その後のプルでも使用できます。

  • プライベートレジストリには、最大 10 個のプルスルーキャッシュルールを作成できます。

  • キャッシュされたイメージが Amazon ECR プライベートレジストリ URI を介してプルされると、イメージのプルは AWS IP アドレスによって開始されます。これにより、パブリックレジストリのプルレートクォータに対して、イメージのプルがカウントされないようになります。

  • キャッシュされたイメージが Amazon ECR プライベートレジストリ URI を介してプルされると、Amazon ECR はリモートリポジトリを 24 時間に 1 回までチェックして、キャッシュされたイメージが最新バージョンであるかどうかを確認します。このタイマーは、キャッシュされたイメージの最後のプルに基づいています。

  • プルスルーキャッシュルールを使用してマルチアーキテクチャイメージをプルすると、マニフェストリストとマニフェストリストで参照されている各イメージが Amazon ECR リポジトリにプルされます。特定のアーキテクチャのみをプルする場合は、マニフェストリストに関連付けられたタグではなく、アーキテクチャに関連付けられたイメージダイジェストまたはタグを使用してイメージをプルできます。

  • Amazon ECR は、サービスにリンクされた IAM ロールを使用します。このロールは、Amazon ECR がユーザーに代わってキャッシュされたイメージのリポジトリを作成し、キャッシュされたイメージをプッシュするために必要なアクセス許可を提供します。プルスルーキャッシュルールを作成すると、サービスにリンクされた IAM ロールが自動的に作成されます。詳細については、「プルスルーキャッシュの Amazon ECR サービスにリンクされたロール」を参照してください。

  • デフォルトで、キャッシュされたイメージをプルする IAM ユーザー、グループ、またはロールには、IAM ポリシーによってアクセス許可が付与されています。Amazon ECR プライベートレジストリアクセス許可ポリシーを使用して、IAM エンティティのアクセス許可のスコープをさらに設定できます。詳細については、「レジストリ許可の使用」を参照してください。

  • プルスルーキャッシュワークフローを使用して作成された Amazon ECR リポジトリは、他の Amazon ECR リポジトリと同様に処理されます。レプリケーションやイメージスキャンなど、すべてのリポジトリ機能がサポートされています。

  • プルスルーキャッシュルールを使用して新しいリポジトリを作成する場合、タグのイミュータビリティはデフォルトで無効になっています。リポジトリでタグのイミュータビリティを手動で有効にした場合、Amazon ECR はキャッシュされたイメージを更新できない場合があります。

  • プルスルーキャッシュルールを使用して新しいリポジトリを作成する場合、AWS KMS 暗号化はデフォルトで無効になっています。AWS KMS 暗号化を使用したい場合、最初のイメージプル前にリポジトリを手動で作成できます。

  • 初めてプルスルーキャッシュルールを使用してイメージをプルするとき、AWS PrivateLink を使って、インターフェイス VPC エンドポイントを使用するように Amazon ECR を設定した場合、NAT ゲートウェイを使用して、同じ VPC 内にパブリックサブネットを作成し、プルが機能するように、プライベートサブネットから NAT ゲートウェイへのすべてのアウトバウンドトラフィックをインターネットにルーティングする必要があります。その後のイメージプルでは、これは必要ありません。詳細については、Amazon Virtual Private Cloud ユーザーガイドの「シナリオ: プライベートサブネットからインターネットにアクセスする」を参照してください。

必要な IAM アクセス許可

プルスルーキャッシュルールを使用するためには、プライベートレジストリへの認証とイメージのプッシュとプルに必要となる Amazon ECR API のアクセス許可に加えて、次のアクセス許可も更に必要となります。

  • ecr:CreatePullThroughCacheRule – プルスルーキャッシュルールを作成するアクセス許可を付与します。このアクセス許可は、アイデンティティに基づく IAM ポリシーを介して付与する必要があります。

  • ecr:BatchImportUpstreamImage – 外部イメージを取得し、プライベートレジストリにインポートするアクセス許可を付与します。このアクセス許可は、プライベートレジストリアクセス許可ポリシー、ID に基づく IAM ポリシー、またはリソースに基づくリポジトリアクセス許可ポリシーを使用して付与できます。レポジトリアクセス許可の使用に関する詳細については、「プライベートリポジトリポリシー」を参照してください。

  • ecr:CreateRepository – プライベートレジストリにリポジトリを作成するアクセス許可を付与します。キャッシュされたイメージを格納するリポジトリがまだ存在しない場合には、この許可が必要となります。このアクセス許可は、アイデンティティに基づく IAM ポリシーまたはプライベートレジストリアクセス許可のいずれかによって付与できます。

レジストリ許可の使用

Amazon ECR プライベートレジストリ許可は、プルスルーキャッシュを使用する個々の IAM エンティティのアクセス許可のスコープ設定に使用できます。レジストリ許可ポリシーによって付与されるアクセス許可よりも多くのアクセス許可が IAM ポリシーによって IAM エンティティに付与される場合、IAM ポリシーが優先されます。たとえば、IAM ユーザーに ecr:* 許可が付与されいる場合には、レジストリレベルで更に許可する必要はありません。

  1. Amazon ECR コンソール (https://console.aws.amazon.com/ecr/) を開きます。

  2. ナビゲーションバーから、プライベートレジストリ許可ステートメントを設定するリージョンを選択します。

  3. ナビゲーションペインで、[Private registry] (プライベートレジストリ)、[Registry permissions] (レジストリー許可) の順に選択します。

  4. [Registry permissions] (レジストリー許可) ページで [Generate statement] (ステートメントを生成) を選択します。

  5. 作成するプルスルーキャッシュ許可ポリシーステートメントごとに、次の操作を行います。

    1. [ポリシータイプ] で、[プルスルーキャッシュポリシー] を選択します。

    2. [ステートメント ID] で、プルスルーキャッシュステートメントポリシーの名前を指定します。

    3. [IAM エンティティ] で、ポリシーに含める IAM ユーザー、グループ、またはロールを指定します。

    4. [リポジトリ名前空間] で、ポリシーを関連付けるプルスルーキャッシュルールを選択します。

    5. [リポジトリ名] で、ルールを適用するリポジトリベース名を指定します。たとえば、Amazon ECR パブリックで Amazon Linux リポジトリを指定する場合、リポジトリ名は amazonlinux になります。

以下の AWS CLI コマンドを使用して、AWS CLI を使用するプライベートレジストリのアクセス許可を指定します。

  1. レジストリポリシーのコンテンツが含まれる ptc-registry-policy.json という名のローカルファイルを作成します。次の例では、ecr-pull-through-cache-user IAM ユーザーにリポジトリを作成し、以前に作成したプルスルーキャッシュルールに関連付けられたアップストリームソースである Amazon ECR Public からイメージをプルするアクセス許可を付与しています。

    {
  "Sid": "PullThroughCacheFromReadOnlyRole",
  "Effect": "Allow",
  "Principal": {
    "AWS": "arn:aws:iam::111122223333:user/ecr-pull-through-cache-user"
  },
  "Action": [
    "ecr:CreateRepository",
    "ecr:BatchImportUpstreamImage"
  ],
  "Resource": "arn:aws:ecr:us-east-1:111122223333:repository/ecr-public/*"
}
    重要

    ecr-CreateRepository 許可は、キャッシュされたイメージを格納するリポジトリがまだ存在しない場合にのみ必要となります。たとえば、リポジトリ作成アクションとイメージをプルするアクションが、管理者や開発者などの別の IAM プリンシパルによって実行されている場合などです。

  2. レジストリポリシーを設定するには、put-registry-policy コマンドを使用します。

    aws ecr put-registry-policy \
     --policy-text file://ptc-registry.policy.json

プルスルーキャッシュルールの作成

Amazon ECR プライベートレジストリにキャッシュするイメージを含む外部パブリックレジストリごとに、プルスルーキャッシュルールを作成します。

プルスルーキャッシュルールを作成するには (AWS Management Console)

  1. Amazon ECR コンソール (https://console.aws.amazon.com/ecr/) を開きます。

  2. ナビゲーションバーから、プライベートレジストリ設定を構成するリージョンを選択します。

  3. ナビゲーションペインで、[Private registry] (プライベートレジストリ)、[Pull through cache] (プルスルーキャッシュ) の順に選択します。

  4. [Pull through cache configuration] (プルスルーキャッシュの設定) ページで、[Add rule] (ルールの追加) を選択します。

  5. [プルスルーキャッシュルールの作成] ページで、次の操作を行います。

    1. [Public registry] (パブリックレジストリ) で、事前設定されたパブリックレジストリの 1 つを選択します。

    2. [Amazon ECR repository namespace] (Amazon ECR リポジトリ名前空間) で、ソースパブリックレジストリからプルされたイメージをキャッシュするときに使用するリポジトリの名前空間を指定します。デフォルトでは、名前空間は設定されていますが、カスタム名前空間も指定できます。

    3. [Save] (保存) を選択して、プルスルーキャッシュルールをレジストリ設定に保存します。

  6. 作成する各プルスルーキャッシュに対して、前のステップを繰り返します。プルスルーキャッシュルールは、リージョンごとに個別に作成されます。

次の AWS CLI コマンドを使用して、AWS CLI を使用するプライベートレジストリのプルスルーキャッシュルールを作成します。

  • create-pull-through-cache-rule (AWS CLI)

    次の例では、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-2

    次の例では、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-2

プルスルーキャッシュイメージの使用

外部パブリックレジストリのプルスルーキャッシュルールが作成されたら、Amazon ECR リポジトリ URI を使用してリモートイメージをプルするだけで、イメージはローカルにキャッシュされます。サポートされているパブリックレジストリの形式を以下に示します。プルスルーキャッシュルールを使用してアップストリームイメージをプルする際にエラーが発生した場合は、プルスルーキャッシュルールを使用してプルするとエラーが発生する を参照してください。最も一般的なエラーと、それらを解決する方法が記載されています。

注記

次の例では、AWS Management Console によって使用されるデフォルトの Amazon ECR リポジトリの名前空間値を使用します。設定した Amazon ECR プライベートリポジトリ URI を使用していることを確認します。

Amazon ECR Public

docker pull aws_account_id.dkr.ecr.region.amazonaws.com/ecr-public/repository_name/image_name:tag

Quay

docker pull aws_account_id.dkr.ecr.region.amazonaws.com/quay/repository_name/image_name:tag

プルスルーキャッシュルールの削除

プルスルーキャッシュルールを削除して、キャッシュ動作を停止できます。プルスルーキャッシュルールを削除しても、キャッシュされたリポジトリやイメージには影響せず、将来のキャッシュ動作を停止するだけです。

プルスルーキャッシュルールを削除するには (AWS Management Console)

  1. Amazon ECR コンソール (https://console.aws.amazon.com/ecr/) を開きます。

  2. ナビゲーションバーから、プライベートレジストリ設定を構成するリージョンを選択します。

  3. ナビゲーションペインで、[Private registry] (プライベートレジストリ)、[Pull through cache] (プルスルーキャッシュ) の順に選択します。

  4. [Pull through cache configuration] (プルスルーキャッシュの設定) ページで、削除するプルスルーキャッシュルールを選択した後、[Delete rule] (ルールの削除) を選択します。

  5. ナビゲーションペインで、[Private registry] (プライベートレジストリ)、[Registry permissions] (レジストリー許可) の順に選択します。

  6. (オプション) [Registry permissions] (レジストリの許可) ページで、既存のレジストリ許可ポリシーステートメントを確認します。削除されたプルスルーキャッシュルールのリポジトリ名前空間に関連付けられているレジストリ許可ポリシーステートメントを削除できます。

次の AWS CLI コマンドを使用して、AWS CLI を使用するプルスルーキャッシュルールを削除します。

  • delete-pull-through-cache-rule (AWS CLI)

    次の例では、ecr-public リポジトリプレフィックスを使用するプルスルーキャッシュルールを削除します。

    aws ecr delete-pull-through-cache-rule \
     --ecr-repository-prefix ecr-public \
     --region us-east-2