Migrating SOCI Index Manifest from v1 to v2 for ECS/Fargate

At my current workplace, we use Seekable OCI (SOCI) to speed up Amazon ECS task launches on AWS Fargate.

Recently, we migrated the SOCI Index Manifest version from v1 to v2. In this article, I'll explain why and how we did it.

Why We Migrated

The reason is simple: v1 support is ending. AWS sent out the following notification:

After careful consideration, we have made the decision to discontinue the support for SOCI Index Manifest v1 for Amazon ECS customers using AWS Fargate launch mode, effective February 9, 2026. Until this date, AWS Fargate customers using Index Manifest v1 will be able to leverage existing indexes and create new indexes using Index Manifest v1 to deploy applications.

Without migrating to v2, task launches would become slower.

How We Migrated

The migration method is also straightforward. In short, we "deployed the new SOCI Index Builder that supports v2." We had been using a different solution with the same name, but it was deprecated without v2 support, so we switched.

Here are the general steps:

1. Prepare the Tool

Clone the SOCI Index Builder Git repository:

git clone https://github.com/awslabs/cfn-ecr-aws-soci-index-builder.git
cd cfn-ecr-aws-soci-index-builder

2. Edit .taskcat.yml

Next, edit .taskcat.yml. This mainly involves changing the deployment region. For example, if you only want to accelerate images in the Tokyo region ECR repository:

--- a/.taskcat.yml
+++ b/.taskcat.yml
@@ -12,11 +12,5 @@ tests:
     parameters:
       SociRepositoryImageTagFilters: "*:*"
     regions:
-      - us-east-1
-      - us-east-2
-      - us-west-1
-      - us-west-2
-      - eu-west-1
-      - eu-west-2
-      - eu-west-3
+      - ap-northeast-1
     template: templates/SociIndexBuilder.yml

3. Run taskcat upload

Then run taskcat upload. This uploads the CloudFormation templates and Lambda function packages to S3.

I recommend running taskcat via Docker rather than installing it locally, as it doesn't support Python 3.14 yet and you probably won't use it very often anyway.

Here's an example of a dry run. Remove --dry-run to actually upload:

docker run --rm \
  -v $(pwd):/mnt \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e AWS_ACCESS_KEY_ID \
  -e AWS_SECRET_ACCESS_KEY \
  -e AWS_SESSION_TOKEN \
  -e GIT_PYTHON_REFRESH=quiet \
  taskcat/taskcat taskcat upload --dry-run

4. Create the CloudFormation Stack

Finally, create a stack using the uploaded CloudFormation template. As documented, the easiest way is through the Management Console.

For reference, here's an example of creating a stack in a single region using Terraform:

locals {
  repository_image_tag_filters = ["*:*"]
}

data "aws_s3_object" "template" {
  bucket = "<your-s3-bucket-name>"
  key    = "cfn-ecr-aws-soci-index-builder/templates/SociIndexBuilder.yml"
}

resource "aws_cloudformation_stack" "this" {
  capabilities     = ["CAPABILITY_IAM"]
  name             = "cfn-ecr-aws-soci-index-builder"
  parameters = {
    IamPermissionsBoundaryArn     = "none"
    QSS3BucketName                = data.aws_s3_object.template.bucket
    QSS3KeyPrefix                 = "${split("/", data.aws_s3_object.template.key)[0]}/"
    SociIndexVersion              = "V2"
    SociRepositoryImageTagFilters = join(",", local.repository_image_tag_filters)
  }
  template_url = format(
    "https://%s.s3.%s.amazonaws.com/%s",
    data.aws_s3_object.template.bucket,
    data.aws_s3_object.template.region,
    data.aws_s3_object.template.key
  )
}

Conclusion

That's how we migrated the SOCI Index Manifest from v1 to v2 for ECS/Fargate.

If you've been using v1 and haven't migrated yet, I recommend doing so; it's not that much work.

Haven't adopted SOCI at all? You can easily speed up your task launches with these four steps. Give it a try!