Update s3-repository docs after upgrade #1356
Conversation
These changes are to bring the docs into alignment with the changes made as part of the S3 upgrade elastic/elasticsearch#126843
| @@ -119,6 +121,8 @@ The following list contains the available client settings. Those that must be st | |||
| `use_throttle_retries` | |||
| : Whether retries should be throttled (i.e. should back off). Must be `true` or `false`. Defaults to `true`. | |||
|
|
|||
| Deprecated: This setting is ignored since version 8.19, retries are always throttled. | |||
There was a problem hiding this comment.
I'd be inclined to remove the mention of this setting entirely in these docs. At least we should just say this setting does nothing rather than documenting its behaviour in older versions. But really there's no need to mention it here even. Its eventual removal will be handled by the upgrade assistant.
|
|
||
| `protocol` | ||
| : The protocol to use to connect to S3. Valid values are either `http` or `https`. Defaults to `https`. When using HTTPS, this repository type validates the repository’s certificate chain using the JVM-wide truststore. Ensure that the root certificate authority is in this truststore using the JVM’s `keytool` tool. If you have a custom certificate authority for your S3 repository and you use the {{es}} [bundled JDK](../../deploy/self-managed/installing-elasticsearch.md#jvm-version), then you will need to reinstall your CA certificate every time you upgrade {{es}}. | ||
|
|
||
| Deprecated: This setting is ignored since version 8.19, specify the protocol in the `endpoint` setting instead. |
There was a problem hiding this comment.
I'd be inclined to remove the mention of this setting entirely in these docs. At least we should just say this setting does nothing rather than documenting its behaviour in older versions. But really there's no need to mention it here even. Its eventual removal will be handled by the upgrade assistant.
That said, as mentioned in this other PR on reflection I'd rather we made it so that a bare endpoint host or host:port value (without a scheme) took its scheme from this setting rather than just always using https://. And then these docs do make a little more sense, but still we should encourage folks not to use it and move the stuff about the trust store into the endpoint docs.
| @@ -133,7 +137,7 @@ In versions `7.0`, `7.1`, `7.2` and `7.3` all bucket operations used the [now-de | |||
| : Whether chunked encoding should be disabled or not. If `false`, chunked encoding is enabled and will be used where appropriate. If `true`, chunked encoding is disabled and will not be used, which may mean that snapshot operations consume more resources and take longer to complete. It should only be set to `true` if you are using a storage service that does not support chunked encoding. See the [AWS Java SDK documentation](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/AmazonS3Builder.html#disableChunkedEncoding--) for details. Defaults to `false`. | |||
|
|
|||
| `region` | |||
| : Allows specifying the signing region to use. Specificing this setting manually should not be necessary for most use cases. Generally, the SDK will correctly guess the signing region to use. It should be considered an expert level setting to support S3-compatible APIs that require [v4 signatures](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) and use a region other than the default `us-east-1`. Defaults to empty string which means that the SDK will try to automatically determine the correct signing region. | |||
| : Specifies the signing region to use. If not specified, the SDK will attempt to guess the signing region to use, but it is recommended to configure this explicitly. Defaults to empty string which means that the SDK will try to automatically determine the correct signing region. | |||
There was a problem hiding this comment.
This setting now specifies more than just the signing region, it's also supposed to determine the regional endpoint too unless the .endpoint setting is configured, which is much more aligned with how the SDK expects to be used. We should put this up near the top since it probably should be set in most configurations now. I'd also recommend we don't mention about guessing the region - we can say that we use the SDK to try and determine the region automatically if not specified.
| @@ -133,7 +137,7 @@ In versions `7.0`, `7.1`, `7.2` and `7.3` all bucket operations used the [now-de | |||
| : Whether chunked encoding should be disabled or not. If `false`, chunked encoding is enabled and will be used where appropriate. If `true`, chunked encoding is disabled and will not be used, which may mean that snapshot operations consume more resources and take longer to complete. It should only be set to `true` if you are using a storage service that does not support chunked encoding. See the [AWS Java SDK documentation](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/AmazonS3Builder.html#disableChunkedEncoding--) for details. Defaults to `false`. | |||
|
|
|||
| `region` | |||
| : Allows specifying the signing region to use. Specificing this setting manually should not be necessary for most use cases. Generally, the SDK will correctly guess the signing region to use. It should be considered an expert level setting to support S3-compatible APIs that require [v4 signatures](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) and use a region other than the default `us-east-1`. Defaults to empty string which means that the SDK will try to automatically determine the correct signing region. | |||
| : Specifies the signing region to use. If not specified, the SDK will attempt to guess the signing region to use, but it is recommended to configure this explicitly. Defaults to empty string which means that the SDK will try to automatically determine the correct signing region. | |||
|
|
|||
| `signer_override` | |||
There was a problem hiding this comment.
This one's also a deprecated no-op and should probably just be removed.
These changes are to bring the docs into alignment with the changes made as part of the S3 upgrade elastic/elasticsearch#126843