メインコンテンツまでスキップ

Amazon ECR の使い方 コンテナイメージを管理するレジストリを AWS CLI で操作する

タグ:

コンテナを使った開発や運用では、ビルドした Docker イメージをどこに保管するかという問題が生じます。AWS を利用している場合、その答えの一つが Amazon ECR（Elastic Container Registry）です。ECR は AWS が提供するフルマネージドのコンテナイメージレジストリで、ECS や EKS などの AWS サービスとシームレスに連携できます。この記事では ECR の基本的な仕組みと、AWS CLI を使ったリポジトリの作成からイメージのプッシュ・プルまでの手順を解説します。

Amazon ECR とは​

Amazon ECR は Docker イメージや OCI（Open Container Initiative）準拠のアーティファクトを保管・管理するためのコンテナイメージレジストリサービスです。Docker Hub のような公開レジストリと異なり、ECR はデフォルトでプライベートなリポジトリを提供します。AWS IAM によってアクセス制御を行うため、細かな権限管理が可能です。

保管したイメージは Amazon ECS・EKS・AWS Batch・App Runner などの AWS コンピューティングサービスから直接参照できます。同一リージョン内であればデータ転送料金もかからないため、AWS 上でコンテナを動かす場合には ECR を選ぶメリットが大きいです。

Amazon Elastic Container Registry とは - Amazon ECR

Amazon ECR は AWS マネージドコンテナイメージレジストリサービスです。

docs.aws.amazon.com

ECR の主な概念​

ECR を使い始める前に、いくつかの用語を整理しておきましょう。

用語説明
レジストリイメージを保管する最上位のコンテナ。アカウントごとに 1 つ作成される
リポジトリイメージをグループ化する単位。myapp/frontend のような名前をつける
イメージタグリポジトリ内の特定イメージを識別するラベル（例: latest、v1.0.0）
イメージダイジェストイメージのハッシュ値。タグよりも一意性が高く、不変の識別子として使える

ECR の URI（Uniform Resource Identifier）は以下の形式になります。デプロイ時にこの URI を指定してイメージを参照します。

{アカウントID}.dkr.ecr.{リージョン}.amazonaws.com/{リポジトリ名}:{タグ}

パブリックレジストリとプライベートレジストリの違い​

ECR にはプライベートレジストリとパブリックレジストリの 2 種類があります。用途に応じて使い分けましょう。

比較項目プライベートレジストリパブリックレジストリ
アクセスIAM 認証が必要認証なしで誰でもプルできる
ホスト名{アカウントID}.dkr.ecr.{リージョン}.amazonaws.compublic.ecr.aws
主な用途社内・プロジェクト内のイメージ管理OSS や公開用イメージの配布
料金ストレージ・データ転送に応じた課金一定量まで無料

社内アプリケーションのイメージを管理する場合はプライベートレジストリ、公開ツールやベースイメージを配布する場合はパブリックレジストリを使いましょう。この記事ではプライベートレジストリを対象に解説します。

セキュリティ機能​

ECR にはイメージのセキュリティを高めるための機能がいくつか用意されています。本番環境で使う場合はこれらの設定を確認しましょう。

機能概要
イメージスキャンプッシュ時や任意のタイミングで OS パッケージの脆弱性を検出できる
イメージの暗号化AWS KMS を使ってリポジトリ内のイメージを暗号化できる
タグのイミュータビリティ同じタグへの上書きプッシュを禁止し、イメージの不変性を保証する
VPC エンドポイントインターネットを経由せず VPC 内から ECR にアクセスできる

Amazon ECR でイメージをスキャンしてソフトウェア脆弱性がないか調べる - Amazon ECR

Amazon ECR イメージスキャンを使用すると、コンテナイメージ内のソフトウェア脆弱性を特定できます。

docs.aws.amazon.com

リポジトリポリシー​

リポジトリには JSON 形式のリポジトリポリシーをアタッチして、どの AWS アカウントやサービスがイメージをプル・プッシュできるかを制御できます。デフォルトでは同一アカウント内の IAM プリンシパルのみがアクセスできますが、別の AWS アカウントからの読み取り専用アクセスを許可するといった設定が可能です。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowCrossAccountPull",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::210987654321:root"
      },
      "Action": [
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage",
        "ecr:BatchCheckLayerAvailability"
      ]
    }
  ]
}

Amazon ECR でのプライベートリポジトリポリシー - Amazon ECR

Amazon ECR では、リソースベースのアクセス権限を使用してリポジトリへのアクセスを制御します。リソースベースのアクセス許可を使用すると、リポジトリにアクセスできるユーザーやロール、およびそれら...

docs.aws.amazon.com

プルスルーキャッシュ​

Docker Hub や Quay.io など外部レジストリのイメージを都度プルしていると、レート制限に引っかかったり、外部レジストリの障害の影響を受けたりすることがあります。プルスルーキャッシュを設定すると、初回アクセス時に外部レジストリのイメージを ECR 内にキャッシュし、以降は ECR 経由でイメージを取得できるようになります。

外部レジストリへの依存を減らしつつ、ECR の IAM 権限管理やプライベートネットワーク経由のアクセスといったメリットをそのまま活用できます。

アップストリームレジストリと Amazon ECR プライベートレジストリの同期 - Amazon ECR

アップストリームレジストリのコンテンツを Amazon ECR プライベートレジストリと同期できます。

docs.aws.amazon.com

AWS CLI で ECR を使ってみる​

AWS CLI を使ってリポジトリの作成からイメージのプッシュ・プルまでを実際に試してみましょう。

リポジトリを作成する​

create-repository コマンドでリポジトリを作成します。オプションの意味は以下の通りです。

  • --image-scanning-configuration scanOnPush=true: プッシュ時に自動でイメージスキャンを実行する
  • --image-tag-mutability IMMUTABLE: 同じタグへの上書きプッシュを禁止する
❯ aws ecr create-repository \
    --repository-name myapp/frontend \
    --image-scanning-configuration scanOnPush=true \
    --image-tag-mutability IMMUTABLE
{
    "repository": {
        "repositoryArn": "arn:aws:ecr:ap-northeast-1:123456789012:repository/myapp/frontend",
        "registryId": "123456789012",
        "repositoryName": "myapp/frontend",
        "repositoryUri": "123456789012.dkr.ecr.ap-northeast-1.amazonaws.com/myapp/frontend",
        "createdAt": "2026-05-14T18:17:26.708000+09:00",
        "imageTagMutability": "IMMUTABLE",
        "imageScanningConfiguration": {
            "scanOnPush": true
        },
        "encryptionConfiguration": {
            "encryptionType": "AES256"
        }
    }
}

repositoryUri に表示された URI をこの後のプッシュ・プルで使用します。

リポジトリポリシーを設定する​

作成したリポジトリに、別の AWS アカウント（例: 210987654321）からの読み取り専用アクセスを許可するポリシーを設定します。

❯ cat << 'EOF' > repo-policy.json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowCrossAccountPull",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::210987654321:root"
      },
      "Action": [
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage",
        "ecr:BatchCheckLayerAvailability"
      ]
    }
  ]
}
EOF
❯ aws ecr set-repository-policy \
    --repository-name myapp/frontend \
    --policy-text file://repo-policy.json

設定したポリシーは get-repository-policy で確認できます。

❯ aws ecr get-repository-policy \
    --repository-name myapp/frontend
{
    "registryId": "123456789012",
    "repositoryName": "myapp/frontend",
    "policyText": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Sid\":\"AllowCrossAccountPull\",\"Effect\":\"Allow\",\"Principal\":{\"AWS\":\"arn:aws:iam::210987654321:root\"},\"Action\":[\"ecr:GetDownloadUrlForLayer\",\"ecr:BatchGetImage\",\"ecr:BatchCheckLayerAvailability\"]}]}"
}

ECR へ認証する​

Docker クライアントから ECR に接続するには、認証トークンを取得してログインする必要があります。get-login-password コマンドでトークンを取得し、docker login に渡します。

❯ aws ecr get-login-password | \
    docker login --username AWS --password-stdin \
    123456789012.dkr.ecr.ap-northeast-1.amazonaws.com
Login Succeeded

Login Succeeded と表示されれば認証完了です。トークンの有効期限は 12 時間のため、CI/CD パイプラインなどで定期的に実行する場合はその都度再認証しましょう。

イメージを取得してタグを付ける​

動作確認用として Docker Hub から nginx:alpine をプルします。

❯ docker pull nginx:alpine

プルしたイメージに ECR の URI 形式でタグを付けます。元のイメージはそのまま残り、同じレイヤーを指す別名が追加されます。

❯ docker tag nginx:alpine \
    123456789012.dkr.ecr.ap-northeast-1.amazonaws.com/myapp/frontend:v1.0.0

イメージをプッシュする​

タグを付けたイメージを ECR へプッシュします。 scanOnPush=true を設定したリポジトリでは、プッシュ完了後に自動でイメージスキャンが実行されます。

❯ docker push \
    123456789012.dkr.ecr.ap-northeast-1.amazonaws.com/myapp/frontend:v1.0.0

プッシュが完了したら、CLI でリポジトリ内のイメージ一覧を確認できます。

❯ aws ecr describe-images \
    --repository-name myapp/frontend
{
    "imageDetails": [
        {
            "registryId": "123456789012",
            "repositoryName": "myapp/frontend",
            "imageDigest": "sha256:abc123def456...",
            "imageTags": [
                "v1.0.0"
            ],
            "imageSizeInBytes": 26092648,
            "imagePushedAt": "2026-05-14T18:22:58.657000+09:00",
            "imageManifestMediaType": "application/vnd.docker.distribution.manifest.v2+json",
            "artifactMediaType": "application/vnd.docker.container.image.v1+json",
            "imageStatus": "ACTIVE"
        }
    ]
}

イメージをプルする​

別の環境から ECR のイメージをプルするには、まず認証を行ってから docker pull を実行します。 ECS や EKS から参照する場合はタスクロールや Node IAM ロールで権限を付与すれば自動認証されますが、ローカルや CI 環境では手動で認証が必要です。

❯ aws ecr get-login-password | \
    docker login --username AWS --password-stdin \
    123456789012.dkr.ecr.ap-northeast-1.amazonaws.com
Login Succeeded

認証が完了したら、イメージをプルします。

❯ docker pull \
    123456789012.dkr.ecr.ap-northeast-1.amazonaws.com/myapp/frontend:v1.0.0

ライフサイクルポリシーで古いイメージを自動削除する​

ECR にイメージを積み重ねていくと、古いイメージが蓄積してストレージコストが増加していきます。ライフサイクルポリシーを設定することで、条件に一致する古いイメージを自動的に削除できます。

ポリシーはルール単位で定義します。以下の例では「タグなしイメージが 5 件を超えたら古い順に削除する」というルールを設定しています。

❯ cat << 'EOF' > lifecycle-policy.json
{
  "rules": [
    {
      "rulePriority": 1,
      "description": "Keep only 5 untagged images",
      "selection": {
        "tagStatus": "untagged",
        "countType": "imageCountMoreThan",
        "countNumber": 5
      },
      "action": {
        "type": "expire"
      }
    }
  ]
}
EOF
❯ aws ecr put-lifecycle-policy \
    --repository-name myapp/frontend \
    --lifecycle-policy-text file://lifecycle-policy.json
{
    "registryId": "123456789012",
    "repositoryName": "myapp/frontend",
    "lifecyclePolicyText": "{\"rules\":[{\"rulePriority\":1,\"description\":\"Keep only 5 untagged images\",\"selection\":{\"tagStatus\":\"untagged\",\"countType\":\"imageCountMoreThan\",\"countNumber\":5},\"action\":{\"type\":\"expire\"}}]}"
}

Amazon ECR でのライフサイクルポリシーを使用したイメージのクリーンアップの自動化 - Amazon ECR

ライフサイクルポリシールールを使用して、自動的にリポジトリをクリーンアップします。

docs.aws.amazon.com

リソースを削除する​

作成したリポジトリを削除します。リポジトリ内にイメージが残っている場合は --force オプションが必要です。

❯ aws ecr delete-repository \
    --repository-name myapp/frontend \
    --force
{
    "repository": {
        "repositoryArn": "arn:aws:ecr:ap-northeast-1:123456789012:repository/myapp/frontend",
        "registryId": "123456789012",
        "repositoryName": "myapp/frontend",
        "repositoryUri": "123456789012.dkr.ecr.ap-northeast-1.amazonaws.com/myapp/frontend",
        "createdAt": "2026-05-14T18:17:26.708000+09:00",
        "imageTagMutability": "IMMUTABLE"
    }
}

まとめ​

Amazon ECR の基本概念と AWS CLI を使ったリポジトリの作成・イメージのプッシュ・プルの手順について説明しました。コンテナを使った開発・運用では、以下のポイントを押さえて ECR を活用しましょう。

  • ECR は AWS が提供するフルマネージドのコンテナイメージレジストリで、IAM による細かなアクセス制御が可能
  • ECS・EKS・App Runner など AWS のコンピューティングサービスとシームレスに連携でき、同一リージョン内のデータ転送料金はかからない
  • 認証トークンを取得して Docker クライアントにログインすることで、ECR へのプッシュ・プルが可能になる
  • タグのイミュータビリティを有効にするとタグの上書きを防止でき、プッシュ時スキャンを有効にすると脆弱性を自動検出できる
  • リポジトリポリシーを設定すれば、他の AWS アカウントからの読み取り専用アクセスなどを制御できる
  • プルスルーキャッシュを使えば、外部レジストリへの依存やレート制限の影響を減らせる
  • ライフサイクルポリシーを設定することで古いイメージを自動削除し、ストレージコストを抑えられる