AWS AmazonECS documentation change
Summary
Updated documentation about SOCI (Seekable OCI) index requirements and verification processes. Added details about SOCI Index Manifest v2 migration, modified image handling procedures, and included CLI examples for verifying SOCI indexes.
Security assessment
The changes focus on operational aspects of SOCI index usage (version migration, image digest changes, and verification methods) rather than addressing security vulnerabilities. While SOCI indexes relate to container image loading efficiency, there's no evidence of a patched security flaw or direct security feature addition. The procedural changes emphasize consistency and validation but don't explicitly mitigate security risks.
Diff
diff --git a/AmazonECS/latest/developerguide/fargate-tasks-services.md b/AmazonECS/latest/developerguide/fargate-tasks-services.md index 6c88903db..53c907c45 100644 --- a//AmazonECS/latest/developerguide/fargate-tasks-services.md +++ b//AmazonECS/latest/developerguide/fargate-tasks-services.md @@ -9 +9 @@ Task definition parametersOperating Systems and architecturesTask CPU and memory -In order to use Fargate, you must configure your task definion to use the Fargate launch type. There are additional considerations when using Fargate. +In order to use Fargate, you must configure your task definition to use the Fargate launch type. There are additional considerations when using Fargate. @@ -204,2 +203,0 @@ For containers that run without SOCI indexes, container images are downloaded co -###### Seekable OCI indexes - @@ -207,0 +206,2 @@ Seekable OCI (SOCI) is an open source technology developed by AWS that can launc +Customers looking to use SOCI will only be able to use the SOCI index manifest v2. Existing customers that have previously used SOCI on Fargate can continue to use the SOCI Index Manifest v1, however we strongly advise those customers migrate to SOCI Index Manifest v2. The SOCI Index Manifest v2 creates an explicit relationship between container images and their SOCI indexes to ensure consistent deployments. + @@ -216,2 +215,0 @@ If you want Fargate to use a SOCI index to lazily load container images in a tas - * Container images in the task definition must have SOCI indexes in the same container registry as the image. - @@ -222 +220,5 @@ If you want Fargate to use a SOCI index to lazily load container images in a tas - * Only container images that use gzip compression or are not compressed are supported. Container images that use zstd compression aren't supported. + * Only container images that use gzip compression, or are not compressed are supported. Container images that use zstd compression aren't supported. + + * For SOCI Index Manifest v2, generating a SOCI index manifest modifies the container image manifest as we add an annotation for the SOCI index. This results in a new container image digest. The contents of the container images filesystem layers do not change. + + * For SOCI Index Manifest v2, when the container image has already been stored in the container image repository, after a SOCI index has been generated, you need to repush the container image. Re-pushing a container image will not increase storage costs by duplicating the filesystem layers, it only uploads a new manifest file. @@ -228 +230 @@ If you want Fargate to use a SOCI index to lazily load container images in a tas - * If you want to prevent a container image from being lazy loaded, delete the SOCI index from the container registry. If a container image in the task doesn't meet one of the considerations, that container image is downloaded by the default method. + * If you want to prevent a container image from being lazy loaded, the container image will need to be repushed without a SOCI index attached. @@ -235 +237 @@ If you want Fargate to use a SOCI index to lazily load container images in a tas -For a container image to be lazy loaded it needs a SOCI index (a metadata file) created and stored in the container image repository along side the container image. To create and push a SOCI index you can use the open source [ soci-snapshotter CLI tool](https://github.com/awslabs/soci-snapshotter) on GitHub. Or, you can deploy the CloudFormation AWS SOCI Index Builder. This is a serverless solution that automatically creates and pushes a SOCI index when a container image is pushed to Amazon ECR. For more information about the solution and the installation steps, see [CloudFormation AWS SOCI Index Builder](https://aws-ia.github.io/cfn-ecr-aws-soci-index-builder/) on GitHub. The CloudFormation AWS SOCI Index Builder is a way to automate getting started with SOCI, while the open source soci tool has more flexibility around index generation and the ability to integrate index generation in your continuous integration and continuous delivery (CI/CD) pipelines. +For a container image to be lazy loaded it needs a SOCI index (a metadata file) created and stored in the container image repository along side the container image. To create and push a SOCI index you can use the open source [ soci-snapshotter CLI tool](https://github.com/awslabs/soci-snapshotter) on GitHub. Or, you can deploy the CloudFormation AWS SOCI Index Builder. This is a serverless solution that automatically creates and pushes a SOCI index when a container image is pushed to Amazon ECR. For more information about the solution and the installation steps, see [CloudFormation AWS SOCI Index Builder](https://awslabs.github.io/cfn-ecr-aws-soci-index-builder/) on GitHub. The CloudFormation AWS SOCI Index Builder is a way to automate getting started with SOCI, while the open source soci tool has more flexibility around index generation and the ability to integrate index generation in your continuous integration and continuous delivery (CI/CD) pipelines. @@ -243 +245,27 @@ For the SOCI index to be created for an image, the image must exist in the conta -To verify that a task was lazily loaded using SOCI, check the task metadata endpoint from inside the task. When you query the task metadata endpoint version 4, there is a `Snapshotter` field in the default path for the container that you are querying from. Additionally, there are `Snapshotter` fields for each container in the `/task` path. The default value for this field is `overlayfs`, and this field is set to `soci` if SOCI is used. . +To verify that a task was lazily loaded using SOCI, check the task metadata endpoint from inside the task. When you query the task metadata endpoint version 4, there is a `Snapshotter` field in the default path for the container that you are querying from. Additionally, there are `Snapshotter` fields for each container in the `/task` path. The default value for this field is `overlayfs`, and this field is set to `soci` if SOCI is used. To verify that a container image has a SOCI Index Manifest v2 attached you can retrieve the Image Index from Amazon ECR using the AWS CLI. + + + IMAGE_REPOSITORY=r + IMAGE_TAG=latest + + aws ecr batch-get-image \ + --repository-name=$IMAGE_REPOSITORY \ + --image-ids imageTag=$IMAGE_TAG \ + --query 'images[0].imageManifest' --output text | jq -r '.manifests[] | select(.artifactType=="application/vnd.amazon.soci.index.v2+json")' + + +To verify that a container image has a SOCI Index Manifest v1 attached you can use the OCI Referrers API. + + + ACCOUNT_ID=111222333444 + AWS_REGION=us-east-1 + IMAGE_REPOSITORY=nginx-demo + IMAGE_TAG=latest + IMAGE_DIGEST=$(aws ecr describe-images --repository-name $IMAGE_REPOSITORY --image-ids imageTag=$IMAGE_TAG --query 'imageDetails[0].imageDigest' --output text) + ECR_PASSWORD=$(aws ecr get-login-password) + + curl \ + --silent \ + --user AWS:$ECR_PASSWORD \ + https://$ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/v2/$IMAGE_REPOSITORY/referrers/$IMAGE_DIGEST?artifactType=application%2Fvnd.amazon.soci.index.v1%2Bjson | jq -r '.' +