Merge pull request mendix#10655 from emirmx/run/3090-update-s3-upgrade-docs

MarkvanMents · web-flow · commit c0bfdf044697 · 2026-01-27T16:10:11.000+01:00
[RUN-3090] Update s3 upgrade docs
diff --git a/content/en/docs/refguide/installation/upgrading-from-10-to-11/_index.md b/content/en/docs/refguide/installation/upgrading-from-10-to-11/_index.md
@@ -169,7 +169,7 @@ After the upgrade, your app may report the following new error: `A microflow tha
 
 You can resolve the error by enabling entity access for the microflow that calls the **ShowHomePage** microflow. However, this may not always align with your intended access control strategy. Alternatively, you can create a custom microflow that includes the [Show home page](/refguide/show-home-page/) activity without enabling entity access. You can then call this new microflow instead of the one in the **System** module. Another approach is to call the **Show home page** activity directly within your microflow.
 
-### Amazon S3 SDK Upgrade
+### Amazon S3 SDK Upgrade {#amazon-s3-sdk-upgrade}
 
 In Mendix 11.6.0 we upgraded the AWS SDK used for accessing S3 storage from version 1 to version 2. SDK version 2 has some [differences](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration-s3.html) which affects our S3 storage implementation.
 
diff --git a/content/en/docs/refguide10/runtime/custom-settings/amazon-s3-sdk-upgrade.md b/content/en/docs/refguide10/runtime/custom-settings/amazon-s3-sdk-upgrade.md
@@ -0,0 +1,47 @@
+---
+title: "Amazon S3 SDK Upgrade"
+url: /refguide10/amazon-s3-sdk-upgrade/
+description: "Describes breaking changes cause by Amazon S3 SDK library upgrade."
+---
+
+## Introduction
+
+In Mendix 10.24.14 we upgraded the AWS SDK used for accessing S3 storage from version 1 to version 2. SDK version 2 has some [differences](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration-s3.html) which affects our S3 storage implementation.
+
+## Considerations When Upgrading Amazon S3 SDK
+
+You will need to consider the following when upgrading to a version of Mendix which uses SDK version 2 for accessing AWS S3 storage.
+
+### `com.mendix.storage.s3.Region` and `com.mendix.storage.s3.EndPoint` Settings
+
+SDK version 2 is stricter with these settings.
+
+* `com.mendix.storage.s3.Region` – always set to the region matching the region of the bucket.
+
+* `com.mendix.storage.s3.EndPoint` – either do not set or set to an endpoint matching the region, for example: `s3.eu-west-1.amazonaws.com`.
+
+When the region is not specified or there is an incompatibility between the two settings above, error logs will contain entries similar to the following:
+
+``` text
+- Unable to load region from any of the providers in the chain.
+- The bucket you are attempting to access must be addressed using the specified endpoint.
+- The authorization header is malformed; the region 'us-east-1' is wrong.
+```
+
+### AWS Signature V2 Support
+
+SDK version 2 does not support AWS Signature v2 which is enabled by the [`com.mendix.storage.s3.UseV2Auth`](/refguide10/custom-settings/#commendixstorages3UseV2Auth) setting. This signature type is deprecated, and is not supported by new regions. For more information, see [AWS's Documentation](https://docs.aws.amazon.com/AmazonS3/latest/API/specify-signature-version.html).
+
+We do not expect this to have any effect when using Amazon S3. It will, however, prevent the use of S3-compatible solutions which only support the v2 signature type. In situations like that, you need to switch to either Amazon S3 or a compatible solution that supports newer signature types.
+
+### Client Side Encryption Changes
+
+Client side encryption can be enabled using the [`com.mendix.storage.s3.EncryptionKeys`](/refguide10/custom-settings/#commendixstorages3EncryptionKeys) setting. Previously, any encryption algorithm supported by the JDK could be used. With the new SDK only AES is supported.
+
+An error similar to the following will be printed in logs when an algorithm other than AES is used:
+
+``` text
+- Unsupported algorithm: DES
+```
+
+If you use an encryption algorithm other than `AES`, then all existing files should be migrated to use `AES` before upgrading to Mendix 10.24.14. This can be done by configuring a new `AES` key and rewriting all file documents.
diff --git a/content/en/docs/refguide9/runtime/custom-settings/amazon-s3-sdk-upgrade.md b/content/en/docs/refguide9/runtime/custom-settings/amazon-s3-sdk-upgrade.md
@@ -0,0 +1,47 @@
+---
+title: "Amazon S3 SDK Upgrade"
+url: /refguide9/amazon-s3-sdk-upgrade/
+description: "Describes breaking changes cause by Amazon S3 SDK library upgrade."
+---
+
+## Introduction
+
+In Mendix 9.24.41 we upgraded the AWS SDK used for accessing S3 storage from version 1 to version 2. SDK version 2 has some [differences](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration-s3.html) which affects our S3 storage implementation.
+
+## Considerations When Upgrading Amazon S3 SDK
+
+You will need to consider the following when upgrading to a version of Mendix which uses SDK version 2 for accessing AWS S3 storage.
+
+### `com.mendix.storage.s3.Region` and `com.mendix.storage.s3.EndPoint` Settings
+
+SDK version 2 is stricter with these settings.
+
+* `com.mendix.storage.s3.Region` – always set to the region matching the region of the bucket.
+
+* `com.mendix.storage.s3.EndPoint` – either do not set or set to an endpoint matching the region, for example: `s3.eu-west-1.amazonaws.com`.
+
+When the region is not specified or there is an incompatibility between the two settings above, error logs will contain entries similar to the following:
+
+``` text
+- Unable to load region from any of the providers in the chain.
+- The bucket you are attempting to access must be addressed using the specified endpoint.
+- The authorization header is malformed; the region 'us-east-1' is wrong.
+```
+
+### AWS Signature V2 Support
+
+SDK version 2 does not support AWS Signature v2 which is enabled by the [`com.mendix.storage.s3.UseV2Auth`](/refguide9/custom-settings/#commendixstorages3UseV2Auth) setting. This signature type is deprecated, and is not supported by new regions. For more information, see [AWS's Documentation](https://docs.aws.amazon.com/AmazonS3/latest/API/specify-signature-version.html).
+
+We do not expect this to have any effect when using Amazon S3. It will, however, prevent the use of S3-compatible solutions which only support the v2 signature type. In situations like that, you need to switch to either Amazon S3 or a compatible solution that supports newer signature types.
+
+### Client Side Encryption Changes
+
+Client side encryption can be enabled using the [`com.mendix.storage.s3.EncryptionKeys`](/refguide9/custom-settings/#commendixstorages3EncryptionKeys) setting. Previously, any encryption algorithm supported by the JDK could be used. With the new SDK only AES is supported.
+
+An error similar to the following will be printed in logs when an algorithm other than AES is used:
+
+``` text
+- Unsupported algorithm: DES
+```
+
+If you use an encryption algorithm other than `AES`, then all existing files should be migrated to use `AES` before upgrading to Mendix 9.24.41. This can be done by configuring a new `AES` key and rewriting all file documents.
diff --git a/content/en/docs/releasenotes/studio-pro/10/10.24.md b/content/en/docs/releasenotes/studio-pro/10/10.24.md
@@ -61,7 +61,7 @@ This is the [LTS](/releasenotes/studio-pro/lts-mts/#lts) version 10 release for
 ### Breaking Changes
     
 - Curly braces in a [placeholder text](/refguide/text-box/#placeholder-text) (for example, `{Name}`) must now be escaped with an extra opening curly brace (for example, `{{Name}`) to prevent the text from being incorrectly interpreted as a placeholder expression.
-- We upgraded the AWS S3 library used for S3 file storage backend from version 1 to 2. This new version of the library has stricter configuration handling and only supports AES for client side encryption.
+- We upgraded the AWS S3 library used for S3 file storage backend from version 1 to 2. This new version of the library has stricter configuration handling and only supports AES for client side encryption. More information can be found in [Amazon S3 SDK Upgrade](/refguide10/amazon-s3-sdk-upgrade/) and [S3 Storage Service Settings](/refguide10/custom-settings/#amazon-s3-storage-service-settings).
 - Added a consistency check for code actions that have a file name that does not match the casing of the document name, which could cause issues on certain operating systems and when deploying to the cloud environment.
 
 ## 10.24.13 {#102413}
diff --git a/content/en/docs/releasenotes/studio-pro/11/11.6.md b/content/en/docs/releasenotes/studio-pro/11/11.6.md
@@ -154,7 +154,7 @@ Additionally, page parameters can now be marked as **Optional** and be given a *
 
 ### Breaking Changes
     
-* We upgraded the AWS S3 library used for S3 file storage backend from version 1 to 2. This new version of the library has stricter configuration handling and only supports AES for client side encryption. More information can be found in [Upgrading from Mendix Studio Pro 10 to 11](/refguide/upgrading-from-10-to-11/) and [S3 Storage Service Settings](/refguide/custom-settings/#amazon-s3-storage-service-settings).
+* We upgraded the AWS S3 library used for S3 file storage backend from version 1 to 2. This new version of the library has stricter configuration handling and only supports AES for client side encryption. More information can be found in [Upgrading from Mendix Studio Pro 10 to 11](/refguide/upgrading-from-10-to-11/#amazon-s3-sdk-upgrade) and [S3 Storage Service Settings](/refguide/custom-settings/#amazon-s3-storage-service-settings).
 * We added a consistency check for code actions that have a filename that does not match the casing of the document name, which could cause issues on certain operating systems, and when deploying to the cloud environment.
 
 ### Known Issues
diff --git a/content/en/docs/releasenotes/studio-pro/9/9.24.md b/content/en/docs/releasenotes/studio-pro/9/9.24.md
@@ -60,7 +60,7 @@ This is the [LTS](/releasenotes/studio-pro/lts-mts/#lts) version 9 release for a
 
 ### Breaking Changes
     
-- We upgraded the AWS S3 library used for S3 file storage backend from version 1 to 2. This new version of the library has stricter configuration handling and only supports AES for client side encryption.
+- We upgraded the AWS S3 library used for S3 file storage backend from version 1 to 2. This new version of the library has stricter configuration handling and only supports AES for client side encryption. More information can be found in [Amazon S3 SDK Upgrade](/refguide9/amazon-s3-sdk-upgrade/) and [S3 Storage Service Settings](/refguide9/custom-settings/#amazon-s3-storage-service-settings).
 
 ## 9.24.40
 
