Amazon Web Services ブログ

SOCI Index Manifest v2 を用いた一貫性のある Amazon ECS デプロイメントの実現

この記事は Improving Amazon ECS deployment consistency with SOCI Index Manifest v2 (記事公開日 : 2025 年 7 月 3 日) の翻訳です。

Seekable OCI (SOCI) は、コンテナイメージ全体をダウンロードする前にコンテナを起動すること (遅延読み込み) で、Amazon Elastic Container Service (Amazon ECS) タスクの起動時間を短縮します。Amazon ECS では、ソフトウェアバージョンの一貫性によって特定の ECS デプロイメント全体で同一のコンテナイメージが使用されることを保証し、信頼性の高いデプロイメントを実現します。しかし、SOCI を用いて ECS タスクを実行する場合、SOCI インデックスはコンテナイメージとは独立しているため、デプロイメントの途中で SOCI インデックスを変更または削除した場合に「一部のタスクは遅延読み込みされるものの、他のタスクはイメージ全体のダウンロードを必要とする」など、起動時間が予測できなくなる可能性がありました。この問題を解決するために、私たちは新しく SOCI Index Manifest v2 を導入しました。これにより、コンテナイメージと SOCI インデックスの間に明示的な関連付けを構築し、SOCI を用いた場合でも一貫したデプロイメントを実現できるようになります。

背景

SOCI を用いてコンテナイメージを遅延読み込みする場合、コンテナランタイムは SOCI インデックスを使用して「各ファイルがコンテナイメージ内のどこに格納されているか」を特定します。SOCI の内部動作に関するブログ記事で説明されているように、SOCI インデックスはコンテナイメージとは独立したアーティファクトであり、イメージレイヤーごとのファイルのインベントリを含みます。以下の図は、SOCI インデックス内の Subject メタデータフィールドを介して、SOCI インデックスとコンテナイメージが関連付けられていることを表しています。この実装を SOCI Index Manifest v1 と呼び、コンテナイメージを変更せずに SOCI インデックスを作成することを可能としていました。

コンテナイメージマニフェストと SOCI Index Manifest v1 の関係性

図 1 : コンテナイメージマニフェストと SOCI Index Manifest v1 の関係性

SOCI Index Manifest v1 では、コンテナイメージと SOCI インデックスの関連付けが一方向な設計によるいくつかの制約がありました。まず、crane や Skopeo などのイメージレプリケーションツールが、リポジトリ間でコンテナイメージを複製する際に SOCI インデックスを見落とすことがよくありました。そのため、SOCI インデックスを個別にプッシュする必要がありました。また、デプロイメントの途中で SOCI インデックスを変更または削除した場合に「一部のタスクは遅延読み込みされるものの、他のタスクはイメージ全体のダウンロードを必要とする」など、デプロイメントの一貫性が損なわれる可能性がありました。

SOCI Index Manifest v2

SOCI Index Manifest v2 では、イメージインデックスを用いて SOCI インデックスとコンテナイメージを関連付けます。イメージインデックスは、マルチアーキテクチャイメージにおける複数プラットフォーム (amd64 や arm64 など) のコンテナイメージを関連付けたり、メタデータを付与するために使用されます。 以下の図は、SOCI Index Manifest v2 において、SOCI インデックスとコンテナイメージが、イメージインデックスのアノテーションを介して相互に関連付けられていることを表しています。

コンテナイメージマニフェストと SOCI Index Manifest v2 の関係性

図 2 : コンテナイメージマニフェストと SOCI Index Manifest v2 の関係性

コンテナイメージと SOCI インデックスの双方向の関連付けにより、一貫性のあるコンテナの実行が可能となります。イメージインデックスを削除または更新しない限り、SOCI インデックスを削除・更新することはできません。また、様々なアーキテクチャにおけるコンテナイメージと SOCI インデックスはすべて、イメージインデックス内で関連付けられるため、SOCI インデックスの大規模な管理が可能となります。これにより、削除やレプリケーションといったライフサイクル管理も合理化されます。

ウォークスルー

SOCI Index Manifest v2 は、soci convert コマンドを使用して作成できます。このウォークスルーでは、Linux 環境でコンテナイメージを操作します。ここでは、まず Finch を使用してコンテナイメージをビルドし、SOCI CLI を使用して SOCI インデックスを作成します。その後、2 つのアーティファクトを Amazon Elastic Container Registry (Amazon ECR) にプッシュします。

1. まず、コンテナイメージをビルドするための Dockerfile を作成します。ここでは、Amazon Linux 2023 のベースイメージを使用して、nginx をインストール・実行するように設定します。

cat <<EOF > Dockerfile 
FROM public.ecr.aws/amazonlinux/amazonlinux:2023-minimal
RUN dnf install -y nginx 
CMD ["nginx", "-g", "daemon off; error_log /dev/stdout info;"]
EOF

2. 続いて、コンテナイメージをビルドします。以下の例では Finch を使用していますが、containerd イメージストアにアーティファクトを保存する任意のコンテナイメージビルダーを使用できます。

export ACCOUNT_ID=$(aws sts get-caller-identity --query "Account" --output text)
export AWS_REGION=us-east-1
sudo finch build \
    --tag $ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/nginx-demo:latest .

3. soci convert コマンドを使用して、SOCI インデックスを作成します。SOCI CLI は SOCI Snapshotter リポジトリからダウンロードできます (convert サブコマンドは v0.10.0 以降で利用可能です)。このとき、お使いのコンテナイメージビルダーに合わせて、適切な名前空間を指定する必要がある点に注意してください。例えば Docker を利用する場合は、containerd イメージストアを利用するように設定した上で --namespace moby を指定してください。

sudo soci --namespace finch convert \
    $ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/nginx-demo:latest \
    $ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/nginx-demo:soci-latest

4. AWS CLI を使用して、Amazon ECR リポジトリを作成します。

aws ecr create-repository \
    --repository-name nginx-demo \
    --region $AWS_REGION

5. Finch を使用して、コンテナイメージと SOCI インデックスを Amazon ECR リポジトリにプッシュします。

sudo finch image push \
    $ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/nginx-demo:soci-latest

認証エラーが出る場合は、Amazon ECR にログインしていることを確認してください。

aws ecr get-login-password --region $AWS_REGION | \
    sudo finch login \
    --username AWS \
    --password-stdin $ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com

6. Amazon ECR リポジトリのアーティファクトを一覧表示するには、Amazon ECR コンソールまたは AWS CLI を使用できます。

aws ecr describe-images \
    --repository-name nginx-demo \
    --region $AWS_REGION

上記コマンドの出力から、リポジトリ内に 3 つのアーティファクト (コンテナイメージ、SOCI インデックス、イメージインデックス) が存在することを確認できます。

{
    "imageDetails": [
        {
            "registryId": "1234567890",
            "repositoryName": "nginx-demo",
            "imageDigest": "sha256:2a2d5af449c44f1658005ed6c2f0f9ee1e99d4013eab9ca572713ed7822cf5c3",
            "imageSizeInBytes": 129069250,
            "imagePushedAt": "2025-05-30T18:01:06.613000+00:00",
            "imageManifestMediaType": "application/vnd.oci.image.manifest.v1+json",
            "artifactMediaType": "application/vnd.oci.image.config.v1+json"
        },
        {
            "registryId": "1234567890",
            "repositoryName": "nginx-demo",
            "imageDigest": "sha256:e9b498d30d84cbb10985a08554a6fff7e6b2bf3edeeaa8bc3a29c35fb6e0fb20",
            "imageSizeInBytes": 3590218,
            "imagePushedAt": "2025-05-30T18:01:06.624000+00:00",
            "imageManifestMediaType": "application/vnd.oci.image.manifest.v1+json",
            "artifactMediaType": "application/vnd.amazon.soci.index.v2+json"
        },
        {
            "registryId": "1234567890",
            "repositoryName": "nginx-demo",
            "imageDigest": "sha256:98dbde520076de139d3f8e9589364daf2ed246edc686f1fd6e47dd3fbadc45a6",
            "imageTags": ["soci-latest"],
            "imageSizeInBytes": 129069250,
            "imagePushedAt": "2025-05-30T18:01:06.887000+00:00",
            "imageManifestMediaType": "application/vnd.oci.image.index.v1+json"
        }
    ]
}

7. イメージインデックスを取得して、コンテナイメージと SOCI インデックスの新しい関係性を確認しましょう。

aws ecr batch-get-image \
    --region $AWS_REGION \
    --repository-name=nginx-demo \
    --image-ids imageTag=soci-latest \
    --query 'images[0].imageManifest' \
    --output text | jq -r '.'

イメージインデックスは SOCI Index Manifest v2 に従い、コンテナイメージと SOCI インデックスがアノテーションを介してお互いを参照していることを確認できます。

{
    "schemaVersion": 2,
    "mediaType": "application/vnd.oci.image.index.v1+json",
    "manifests": [
        {
            "mediaType": "application/vnd.oci.image.manifest.v1+json",
            "digest": "sha256:2a2d5af449c44f1658005ed6c2f0f9ee1e99d4013eab9ca572713ed7822cf5c3",
            "size": 699,
            "annotations": {
                "com.amazon.soci.index-digest": "sha256:e9b498d30d84cbb10985a08554a6fff7e6b2bf3edeeaa8bc3a29c35fb6e0fb20"
            },
            "platform": {
                "architecture": "amd64",
                "os": "linux"
            }
        },
        {
            "mediaType": "application/vnd.oci.image.manifest.v1+json",
            "digest": "sha256:e9b498d30d84cbb10985a08554a6fff7e6b2bf3edeeaa8bc3a29c35fb6e0fb20",
            "size": 1038,
            "annotations": {
                "com.amazon.soci.image-manifest-digest": "sha256:2a2d5af449c44f1658005ed6c2f0f9ee1e99d4013eab9ca572713ed7822cf5c3"
            },
            "platform": {
                "architecture": "amd64",
                "os": "linux"
            },
            "artifactType": "application/vnd.amazon.soci.index.v2+json"
        }
    ]
}

これで、ECS タスク定義でこのコンテナイメージのタグまたはダイジェストを参照し、AWS Fargate 上でコンテナイメージを遅延読み込みできるようになりました。SOCI を使用してコンテナイメージを遅延読み込みするために、ECS タスク定義や ECS サービス定義にフラグやパラメーターを追加する必要はありません。

後片付け

余分なコストの発生を防ぐために、Amazon ECR リポジトリを削除しましょう。

aws ecr delete-repository \
    --repository-name nginx-demo \
    --region $AWS_REGION \
    --force

考慮事項

SOCI Index Manifest v2 のリリースに関して、いくつかの考慮事項があります。

  • SOCI Index Manifest v2 は、SOCI Snapshotter v0.10 以降、および AWS Fargate プラットフォームバージョン 1.4.0 でサポートされています。
  • AWS Fargate で初めて SOCI を使用するお客様は、SOCI Index Manifest v2 のみを使用できます。この場合、AWS Fargate は SOCI Index Manifest v1 に関連付けられたコンテナイメージを遅延読み込みせず、コンテナイメージ全体をダウンロードしてからコンテナを起動します。
  • 過去に AWS Fargate で SOCI を使用したことがあるお客様は、引き続き SOCI Index Manifest v1 を使用できます。ただし、v2 への移行を強く推奨します。この場合、AWS Fargate は SOCI Index Manifest v1 または v2 のいずれかに関連付けられたコンテナイメージを遅延読み込みします。
  • SOCI Index Manifest v1 から v2 に移行するには、ウォークスルーで説明した手順に従って SOCI インデックスマニフェストを作成、プッシュし直す必要があります。
  • AWS Fargate が使用する snapshotter (soci または overlayfs) は、ECS タスクメタデータエンドポイントで公開されます。この値は amilazy init コンテナを使用してログに出力し、一元的に管理できます。
  • SOCI Index Manifest v2 を作成すると、SOCI インデックスに関連するアノテーションが追加され、コンテナイメージマニフェストが変更されるため、コンテナイメージダイジェストも再生成されます。このとき、コンテナイメージのイメージレイヤーの内容は変更されません。
  • コンテナイメージがすでにコンテナイメージリポジトリに保存されている場合、SOCI インデックスを作成後、コンテナイメージをプッシュし直す必要があります。このとき、すでにレポジトリに存在するイメージレイヤーのアップロードはスキップされるため、イメージレイヤー重複によるストレージコストの増加は発生せず、新しいマニフェストファイルのみがアップロードされます。
  • SOCI インデックス作成の自動化ソリューションである SOCI Index Builder を使用している場合、最新バージョンにアップデートすることで SOCI Index Manifest v2 を利用できます。

最新情報については、Amazon ECS ドキュメントまたは SOCI Snapshotter リポジトリをご確認ください。

まとめ

Seekable OCI (SOCI) は、コンテナイメージを遅延読み込みすることで AWS Fargate のタスク起動時間を短縮します。今回導入された SOCI Index Manifest v2 によって、SOCI を使用する際の ECS デプロイメントの一貫性について、より高い信頼性を提供するようになりました。コンテナイメージと SOCI インデックスの明示的な関連付けにより、SOCI インデックスの大規模な管理も容易になります。AWS Fargate 上の ECS タスクにおいて SOCI を利用開始するには、Amazon ECS 開発者ガイドおよび SOCI Toolbox をご確認ください。また、SOCI プロジェクトと SOCI Index Manifest v2 の詳細については、SOCI Snapshotter プロジェクトをご覧ください。