# Update using AWS CloudFormation
**Important**
Dynamic Image Transformation for Amazon CloudFront version 6.0 and newer include significant changes, and you can’t update the solution from versions prior to 6.0 to version 6.0 or later. To use version 6.0 or later, launch a new stack using version 6.x of the CloudFormation template and [uninstall](uninstall-the-solution.md) your previous version of this solution.
S3 Object Lambda has been deprecated. Amazon S3 Object Lambda will no longer be open to new customers starting on November 7, 2025. If you were not an existing user of S3 Object Lambda before November 7, 2025, select ‘No'. For more information, please visit https://docs.aws.amazon.com/AmazonS3/latest/userguide/amazons3-ol-change.html.
Modifying the architecture of an existing deployment by changing the value of the `Enable S3 Object Lambda` template parameter will cause a deletion and recreation of the CloudFront distribution associated with the deployment. This recreation will result in a new API endpoint URL and an empty cache. For information on a workaround to use an alternate architecture type while maintaining the current endpoint URL and cache, refer to the instructions on [maintaining the existing endpoint and cache when modifying architecture type](maintain-endpoint-cache-architecture.md).
**Important**
**Version 8.0.0 Breaking Changes:**
Dynamic Image Transformation for Amazon CloudFront version 8.0.0 introduces significant architectural changes and is **not compatible** with previous versions. This release includes:
**New ECS Architecture**: The new high-performance container-based architecture cannot be deployed as an update to existing stacks
**Breaking Changes**: Version 8.0.0 includes fundamental changes to the solution architecture, configuration, and feature set
**Clean Deployment Required**: To use the ECS architecture or any v8.0.0 features, you must deploy a **new stack** using the v8.0.0 CloudFormation template
**Migration Path:** - **Lambda Architecture**: Existing deployments can be updated to v8.0.0 Lambda template for maintenance and security updates - **ECS Architecture**: Requires a completely new deployment - cannot be updated from any previous version - **Feature Access**: Advanced features (transformation policies, non-S3 origins, Admin UI) are only available in the new ECS architecture
**Recommendation**: Deploy the new ECS architecture as a separate stack, test thoroughly, then migrate traffic and [uninstall](uninstall-the-solution.md) the previous version.
# Update Lambda architecture
Follow these steps to update an existing Lambda architecture deployment to the latest version:
1. Sign in to the [AWS CloudFormation console](https://console.aws.amazon.com/cloudformation/), select your existing Dynamic Image Transformation for Amazon CloudFront CloudFormation stack, and select **Update**.
1. Select **Replace current template**.
1. Under **Specify template**:
1. Select **Amazon S3 URL**.
1. Copy the link of the `dynamic-image-transformation-for-amazon-cloudfront-lambda.template` [AWS CloudFormation template](aws-cloudformation-template.md).
1. Paste the link in the **Amazon S3 URL** box.
1. This link will point to the latest template by default, to modify which version you update to, replace the word `latest` with the desired version.
1. For example: `https://solutions-reference.s3.amazonaws.com/dynamic-image-transformation-for-amazon-cloudfront/latest/dynamic-image-transformation-for-amazon-cloudfront-lambda.template` would become `https://solutions-reference.s3.amazonaws.com/dynamic-image-transformation-for-amazon-cloudfront/v8.0.0/dynamic-image-transformation-for-amazon-cloudfront-lambda.template`
**Note**
Alongside the rename in v7.0.0 from Serverless Image Handler to Dynamic Image Transformation for Amazon CloudFront, the location of the cloudformation template has changed, if you’d like to follow the above instructions for a version before v7.0.0, use the following template URL as a baseline: https://solutions-reference.s3.amazonaws.com/serverless-image-handler/latest/serverless-image-handler.template
1. Verify that the correct template URL shows in the *\$1Amazon S3 URL\$1* text box, and choose **Next**. Choose **Next** again.
1. Under **Parameters**, review the parameters for the template and modify them as necessary. For details about the parameters, see [Lambda architecture template parameters](lambda-parameters.md).
1. Choose **Next**.
1. On the **Configure stack options** page, choose **Next**.
1. On the **Review** page, review and confirm the settings. Select the box acknowledging that the template creates IAM resources.
1. Choose **View change set** and verify the changes.
1. Choose **Update stack** to deploy the stack.
You can view the status of the stack in the AWS CloudFormation console in the **Status** column. You should receive an `UPDATE_COMPLETE` status in approximately 15 minutes.
# Update ECS architecture
Follow these steps to update an existing ECS architecture deployment to the latest version:
1. Sign in to the [AWS CloudFormation console](https://console.aws.amazon.com/cloudformation/), select your existing Dynamic Image Transformation for Amazon CloudFront CloudFormation stack, and select **Update**.
1. Select **Replace current template**.
1. Under **Specify template**:
1. Select **Amazon S3 URL**.
1. Copy the link of the `dynamic-image-transformation-for-amazon-cloudfront-ecs.template` [AWS CloudFormation template](aws-cloudformation-template.md).
1. Paste the link in the **Amazon S3 URL** box.
1. This link will point to the latest template by default.
1. Verify that the correct template URL shows in the *\$1Amazon S3 URL\$1* text box, and choose **Next**. Choose **Next** again.
1. Under **Parameters**, review the parameters for the template and modify them as necessary. For details about the parameters, see [ECS architecture template parameters](ecs-parameters.md).
1. Choose **Next**.
1. On the **Configure stack options** page, choose **Next**.
1. On the **Review** page, review and confirm the settings. Select the box acknowledging that the template creates IAM resources.
1. Choose **View change set** and verify the changes.
1. Choose **Update stack** to deploy the stack.
You can view the status of the stack in the AWS CloudFormation console in the **Status** column. You should receive an `UPDATE_COMPLETE` status in approximately 15 minutes.
# Backward compatibility
**Note**
**Lambda Architecture Only**: The backward compatibility features described in this section only apply to the Lambda architecture template. The ECS architecture uses a different request format and does not support legacy Thumbor or custom request formats.
This solution is compatible with legacy image request formats, including the Thumbor and Custom (with rewrite function) formats from previous versions of this solution. If you are using a previous version of this solution (version 3.x and earlier) and have image requests formatted for use with that version, review the following note to ensure minimal breaking changes or parities.
**Note**
Legacy requests (Thumbor and custom) will source images from the first bucket in the `SOURCE_BUCKETS` environment variable by default. To use a different bucket, you can use the `s3:BucketName` tag in your request or you can adjust which bucket is first in the environment variables section of your image handler Lambda function. See [Using AWS Lambda environment variables](https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html) in the *AWS Lambda Developer Guide* for more information.
# Thumbor compatibility
You can specify Thumbor image requests as you normally would, with filters and other relevant properties added on as suffixes to the default CloudFront **ApiEndpoint**. For more information about using Thumbor, see [List of supported Thumbor filters](use-supported-thumbor-filters.md).
**Note**
Dynamic Image Transformation for Amazon CloudFront includes a Thumbor-style interface in the API; however, those requests are mapped to comparable Sharp library calls, and might not include all available Thumbor filters. For more information about available Thumbor-style filters, see [List of supported Thumbor filters](use-supported-thumbor-filters.md).
# Custom compatibility
You can specify custom image requests that used the version 3.x and earlier solution versions' rewrite feature as you normally would. First, you must update the `REWRITE_MATCH_PATTERN` and `REWRITE_SUBSTITUTION` environment variables for your image handler function with the appropriate (JavaScript/ECMAScript-compatible) regular expressions and strings. For example:
```
https://.cloudfront.net/
```
For more information about using custom image requests, see [Custom image requests](custom-image-requests.md).
# Maintain existing endpoint and cache when modifying architecture type
With the release of the Object Lambda architecture, customers have the ability to enable an architecture which supports larger images. Modifying an existing distribution to use this architecture will cause a deletion and recreation of the CloudFront distribution associated with the deployment. This will result in a change to the domain name, as well as the cache being cleared. The following workaround can be used to modify the architecture type while avoiding this deletion.
**Note**
This workaround is not officially supported, and may run into instability. This workaround requires that both stacks are maintained in order to maintain functionality. Any updates to the original stack may undo some of the changes performed here. You may experience downtime
1. Follow the process for deploying a new Dynamic Image Transformation for Amazon CloudFront stack. Refer to [deploy the solution](deploy-the-solution.md) for additional guidance on this step.
1. Modify the Enable S3 Object Lambda template parameter to select your desired architecture.
1. Set Use Existing CloudFront Distribution to `Yes`
1. Set Existing CloudFront Distribution Id to the ID of the Image Handler distribution for your existing stack.
1. Set the remaining template parameters to the same values used in the original deployment.
1. Deploy the stack.
1. Upon completion of the deployment, follow the instructions in [Attaching an Existing CloudFront distribution](attaching-existing-distribution.md) to attach the CloudFront distribution referenced to the newly deployed resources. This will require that you overwrite the existing values on the distribution.