Improving Amazon ECS deployment consistency with SOCI Index Manifest v2

Seekable OCI (SOCI) helps Amazon Elastic Container Service (Amazon ECS) customers reduce task launch times by starting containers before their images are fully downloaded. To ensure reliable deployments, Amazon ECS software version consistency ensures that the same container image is used throughout an ECS deployment. However, when running ECS tasks with SOCI, there was still an element of unpredictability. SOCI indexes are independent from container images, modifying or removing an index during a deployment could cause unpredictable launch times, with some tasks being lazy loaded while others requiring full image downloads. To address this, we are introducing SOCI index manifest v2, which creates an explicit relationship between container images and their SOCI indexes to ensure consistent deployments.

Background

When lazy loading container images with SOCI, the container runtime uses a SOCI index to identify where within a container image each file is stored. As described in the SOCI under the hood post, the SOCI index is a separate artifact from the container image, containing an inventory of files in each filesystem layer. The following diagram shows the relationship between a SOCI index and a container image, linked to each other through a Subject metadata field in the SOCI index. We refer to this implementation as the SOCI index manifest v1, and it allowed a container image to be indexed without being modified.

The relationship between a container image manifest and a SOCI Index Manifest v1

There were a few limitations with the SOCI index manifest v1 design, due to the loose connection between the container image and the SOCI index. First, image replication tooling (such as crane and Skopeo) often missed the SOCI index when replicating container images between repositories. This led to the need to separately push a SOCI index. Furthermore, if someone deleted or modified the SOCI index during an ECS deployment, it was common to have an inconsistent deployment, with some lazy loaded tasks and some non-lazy loaded tasks.

SOCI index manifest v2

The SOCI index manifest v2 binds the SOCI index to the container image through an image index. Developers commonly use image indexes in multi-architecture images to either link multiple platforms of a container images (such as amd64 and arm64) or to attach metadata (such as an attestation). In SOCI index manifest v2, we use an image index to attach metadata to the container image, linking the container image manifest and the SOCI index manifest, as shown in the following diagram.

The relationship between a container image manifest and a SOCI Index Manifest v2

The new relationship between the SOCI index and container image enforces consistent runtime behavior. A SOCI index cannot be deleted or modified without removing or pushing a new image index. Furthermore, you can now manage SOCI indexes at scale, with all architectures of a container image and all SOCI indexes all tied together by the image index. This streamlines lifecycle tasks such as deletion and replication.

Walkthrough

To generate a SOCI index manifest v2 you can use the new convert subcommand within the soci CLI. In this walkthrough we use a Linux based workstation to interact with container images. First we use Finch to build a container image, next we use the soci CLI to create a SOCI index, and finally we push both artifacts to Amazon Elastic Container Registry (Amazon ECR).

1. First, we create a Dockerfile from which to build our container image. This is a Dockerfile that starts from an Amazon Linux 2023 base image and installs 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. To build the container image we use Finch, but you can use any container image builder that stores its artifacts in the containerd image store.

export ACCOUNT_ID=1234567890
export AWS_REGION=us-east-1
sudo finch build --tag $ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/nginx-demo:latest .

3. Create a SOCI index using the new convert subcommand in the soci CLI. Note you may need to adjust the namespace flag depending on your container image builder (such as --namespace moby). You can download the soci CLI from the upstream SOCI Snapshotter repository (version 0.10.0 or higher).

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. Create an Amazon ECR repository using the aws CLI.

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

5. Push the container image and the SOCI index up to the Amazon ECR repository using Finch.

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

6. To list all artifacts within an Amazon ECR repository, you can use the Amazon ECR console or the aws CLI.

aws ecr describe-images \
    --repository-name nginx-demo

In the output you should see three artifacts in the repository: the container image, the SOCI index, and the image index.

{
    "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. To demonstrate the new relationship between the container image and the SOCI index, you can inspect the contents of the image index using the aws CLI.

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

You should now see the output of the SOCI index manifest v2, with references to both the container image and the SOCI index.

{
    "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"
        }
    ]
}

This container image can now be lazy loaded on AWS Fargate by referring to the container image tag or digest in the ECS task definition. There are no other flags or parameters to pass into a task definition or ECS service definition to lazy load a container image using SOCI.

Cleaning up

The Amazon ECR repository can be cleaned up to prevent ongoing costs:

aws ecr delete-repository \
    --repository-name nginx-demo \
    --force

Considerations

There are several considerations with the release of SOCI index manifest v2:

• The SOCI index manifest v2 is supported in the upstream SOCI snapshotter v0.10 and within AWS Fargate platform version 1.4.0.
• Customers new to SOCI on AWS Fargate can only use SOCI index manifest v2. For these customers, Fargate does not lazy load a container image attached to a SOCI index manifest v1 and fails back to fully downloading the container image.
• Customers that have previously used SOCI on Fargate can continue to use the SOCI index manifest v1. However, we strongly advise customers migrate to v2. For these existing customers, Fargate lazy loads a container image attached to either a SOCI index manifest v1 or SOCI index manifest v2.
• To migrate from SOCI index manifest v1 to SOCI index manifest v2, customers will need to recreate and repush the SOCI index manifest using the steps highlighted previously in the walkthrough.
• The snapshotter used by Fargate (soci or overlayfs) is exposed in the ECS Task Metadata Endpoint. This value can be centrally stored using the amilazy utility.
• Generating a SOCI index manifest v2 modifies the container image manifest as we add an annotation for the SOCI index, resulting in a new container image digest. The contents of the container image’s filesystem layers do not change.
• If the container image has already been stored in the container image repository, after a SOCI index has been generated, then you must repush the container image. Repushing a container image does not increase storage costs by duplicating the filesystem layers, it only uploads a new manifest file.
• If customers are using the SOCI index builder, a way to automate the generation of SOCI index, then they must update to a new version of the builder to support SOCI index manifests v2.

For the latest information go to the Amazon ECS documentation or the upstream SOCI Snapshotter repository.

Conclusion

Seekable OCI (SOCI) can reduce task launch times on AWS Fargate, and now SOCI index manifest v2 provides customers with more confidence in their ECS deployment consistency when using SOCI. The explicit relationship between the container image and the SOCI index also make it easier to manage the SOCI index at scale. To help you get started with SOCI on Amazon ECS with AWS Fargate, go to the documentation and the SOCI toolbox. To learn more about the upstream SOCI project and the SOCI index manifest v2, go to the upstream SOCI Snapshotter project.

About the author

Olly Pomeroy is a Senior Container Specialist Solution Architect at AWS.