Add note for us-east-1 endpoint mode

[logwolvy]

Documentation fix related to #2718

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

1. To make sure we include your contribution in the release notes, please make sure to add description entry for your changes in the "unreleased changes" section of the CHANGELOG.md file (at corresponding gem). For the description entry, please make sure it lives in one line and starts with Feature or Issue in the correct format.

2. For generated code changes, please checkout below instructions first:
   https://github.com/aws/aws-sdk-ruby/blob/version-3/CONTRIBUTING.md

Thank you for your contribution!

[mullermp]

Thanks for opening a pull request. I'm in favor of adding some notes around the linked issue but I don't think this is the correct place or change. The s3_us_east_1_regional_endpoint option already states this proposed behavior. The issue linked is in regards to FIPS endpoints with DNS incompatible buckets. s3_us_east_1_regional_endpoint seems to only matter when fips is used, regardless of DNS compatible bucket or not.

Behavior matrix for a DNS incompatible bucket (one with dots):

# no fips, us-east-1, regional endpoint
Aws::S3::Client.new(use_fips_endpoint: false, region: 'us-east-1', s3_us_east_1_regional_endpoint: 'regional').list_objects(bucket: 'mamuller.us-east-1')
# succeeds

# no fips, us-east-1, global endpoint
Aws::S3::Client.new(use_fips_endpoint: false, region: 'us-east-1', s3_us_east_1_regional_endpoint: 'legacy').list_objects(bucket: 'mamuller.us-east-1')
# succeeds

# fips, us-east-1, regional endpoint
Aws::S3::Client.new(use_fips_endpoint: true, region: 'us-east-1', s3_us_east_1_regional_endpoint: 'regional').list_objects(bucket: 'mamuller.us-east-1')
# cannot connect

# fips, us-east-1, global endpoint
Aws::S3::Client.new(use_fips_endpoint: true, region: 'us-east-1', s3_us_east_1_regional_endpoint: 'legacy').list_objects(bucket: 'mamuller.us-east-1')
# cannot connect

Behavior matrix for a DNS compatible bucket (one without dots):

# no fips, us-east-1, regional endpoint
Aws::S3::Client.new(use_fips_endpoint: false, region: 'us-east-1', s3_us_east_1_regional_endpoint: 'regional').list_objects(bucket: 'mamuller-us-east-1')
# success

# no fips, us-east-1, global endpoint
Aws::S3::Client.new(use_fips_endpoint: false, region: 'us-east-1', s3_us_east_1_regional_endpoint: 'legacy').list_objects(bucket: 'mamuller-us-east-1')
# success

# fips, us-east-1, regional endpoint
 Aws::S3::Client.new(use_fips_endpoint: true, region: 'us-east-1', s3_us_east_1_regional_endpoint: 'regional').list_objects(bucket: 'mamuller-us-east-1')
# success

# fips, us-east-1, global endpoint
Aws::S3::Client.new(use_fips_endpoint: true, region: 'us-east-1', s3_us_east_1_regional_endpoint: 'legacy').list_objects(bucket: 'mamuller-us-east-1')
# failure

[mullermp]

I think we need 2 documentation changes here:

1. In s3_us_east_1_regional_endpoint plugin, either update the documentation or behavior.

Documentation update:

          docstring: <<-DOCS) do |cfg|
Pass in `regional` to enable the `us-east-1` regional endpoint.
Defaults to `legacy` mode which uses the global endpoint. When
using a FIPS endpoint with `us-east-1`, this option must be set to
`regional`.
          DOCS

OR behavior update:

          # only modify non-custom non-fips endpoints
          if config.regional_endpoint && config.region == 'us-east-1' &&
             !config.use_fips_endpoint
            handlers.add(Handler)
          end

Alternatively, we can modify s3_us_east_1_regional_endpoint config to be 'regional' when use_fips_endpoint is true - this may be safe, needs investigation.

2. Add S3 specific use_fips_endpoint documentation. I believe that config options in the Ruby SDK can be nested/overwritten. In the BucketDns plugin, we can re-define use_fips_endpoint:

        option(:use_fips_endpoint,
          doc_type: 'Boolean',
          docstring: <<-DOCS)
  When set to `true`, fips compatible endpoints will be used if available.
  When a `fips` region is used, the region is normalized and this config
  is set to `true`.

  FIPS endpoints cannot be used with DNS incompatible buckets.
          DOCS