|
| 1 | +pr: 126843 |
| 2 | +summary: Upgrade `repository-s3` to AWS SDK v2 |
| 3 | +area: Snapshot/Restore |
| 4 | +type: breaking |
| 5 | +issues: |
| 6 | + - 120993 |
| 7 | +highlight: |
| 8 | + title: Upgrade `repository-s3` to AWS SDK v2 |
| 9 | + body: >- |
| 10 | + In earlier versions of {es} the `repository-s3` plugin was based on the AWS |
| 11 | + SDK v1. AWS will withdraw support for this SDK before the end of the life |
| 12 | + of {es} {minor-version} so we have migrated this plugin to the newer AWS SDK v2. |
| 13 | +
|
| 14 | + The two SDKs are not quite compatible, so please check the breaking changes |
| 15 | + documentation and test the new version thoroughly before upgrading any |
| 16 | + production workloads. |
| 17 | + notable: true |
| 18 | +breaking: |
| 19 | + title: Upgrade `repository-s3` to AWS SDK v2 |
| 20 | + area: Cluster and node setting |
| 21 | + details: >- |
| 22 | + In earlier versions of {es} the `repository-s3` plugin was based on the AWS |
| 23 | + SDK v1. AWS will withdraw support for this SDK before the end of the life |
| 24 | + of {es} {minor-version} so we must migrate to the newer AWS SDK v2. |
| 25 | +
|
| 26 | + Unfortunately there are several differences between the two AWS SDK |
| 27 | + versions which may require you to adjust your system configuration when |
| 28 | + upgrading to {es} {minor-version} or later. These differences include, but |
| 29 | + may not be limited to, the following items. |
| 30 | +
|
| 31 | + * AWS SDK v2 requires users to specify the region to use for signing |
| 32 | + requests, or else to run in an environment in which it can determine the |
| 33 | + correct region automatically. The older SDK would try to determine the |
| 34 | + region based on the endpoint URL as specified with the |
| 35 | + `s3.client.${CLIENT_NAME}.endpoint` setting, together with other data |
| 36 | + drawn from the operating environment, and would ultimately fall back to |
| 37 | + `us-east-1` if no better value could be found. |
| 38 | +
|
| 39 | + * AWS SDK v2 does not support the EC2 IMDSv1 protocol. |
| 40 | +
|
| 41 | + * AWS SDK v2 does not support the |
| 42 | + `com.amazonaws.sdk.ec2MetadataServiceEndpointOverride` system property. |
| 43 | +
|
| 44 | + * AWS SDK v2 does not permit specifying a choice between HTTP and HTTPS so |
| 45 | + the `s3.client.${CLIENT_NAME}.protocol` setting is deprecated and no longer |
| 46 | + has any effect. |
| 47 | +
|
| 48 | + * AWS SDK v2 does not permit control over throttling for retries, so the |
| 49 | + the `s3.client.${CLIENT_NAME}.use_throttle_retries` setting is deprecated |
| 50 | + and no longer has any effect. |
| 51 | +
|
| 52 | + * AWS SDK v2 requires the use of the V4 signature algorithm, so the |
| 53 | + `s3.client.${CLIENT_NAME}.signer_override` setting is deprecated and no |
| 54 | + longer has any effect. |
| 55 | +
|
| 56 | + * AWS SDK v2 does not support the `log-delivery-write` canned ACL. |
| 57 | +
|
| 58 | + * AWS SDK v2 counts 4xx responses differently in its metrics reporting. |
| 59 | +
|
| 60 | + * AWS SDK v2 always uses the regional STS endpoint, whereas AWS SDK v2 |
| 61 | + could use either a regional endpoint or the global |
| 62 | + `https://sts.amazonaws.com` one. |
| 63 | +
|
| 64 | + impact: >- |
| 65 | + If you use the `repository-s3` module, test your upgrade thoroughly before |
| 66 | + upgrading any production workloads. |
| 67 | +
|
| 68 | + Adapt your configuration to the new SDK functionality. This includes, but |
| 69 | + may not be limited to, the following items. |
| 70 | +
|
| 71 | + * Specify the correct signing region using the |
| 72 | + `s3.client.${CLIENT_NAME}.region` setting on each node. {es} will try and |
| 73 | + determine the correct region based on the endpoint URL and other data |
| 74 | + drawn from the operating environment but cannot guarantee to do so |
| 75 | + correctly in all cases. |
| 76 | +
|
| 77 | + * If you use IMDS to determine the availability zone of a node or to obtain |
| 78 | + credentials for accessing the EC2 API, ensure that it supports the IMDSv2 |
| 79 | + protocol. |
| 80 | +
|
| 81 | + * If applicable, discontinue use of the |
| 82 | + `com.amazonaws.sdk.ec2MetadataServiceEndpointOverride` system property. |
| 83 | +
|
| 84 | + * If applicable, specify that you wish to use the insecure HTTP protocol to |
| 85 | + access the S3 API by setting `s3.client.${CLIENT_NAME}.endpoint` to a URL |
| 86 | + which starts with `http://`. |
| 87 | +
|
| 88 | + * If applicable, discontinue use of the `log-delivery-write` canned ACL. |
| 89 | +
|
| 90 | + notable: true |
0 commit comments