Using Amazon S3 dual-stack endpoints
Amazon S3 dual-stack endpoints support requests to S3 buckets over IPv6 and IPv4. This section describes how to use dual-stack endpoints.
Topics
Amazon S3 dual-stack endpoints
When you make a request to a dual-stack endpoint, the bucket URL resolves to an IPv6 or an IPv4 address. For more information about accessing a bucket over IPv6, see Making requests to Amazon S3 over IPv6.
When using the REST API, you directly access an Amazon S3 endpoint by using the endpoint name (URI). You can access an S3 bucket through a dual-stack endpoint by using a virtual hosted-style or a path-style endpoint name. Amazon S3 supports only regional dual-stack endpoint names, which means that you must specify the region as part of the name.
Use the following naming conventions for the dual-stack virtual hosted-style and path-style endpoint names:
-
Virtual hosted-style dual-stack endpoint:
bucketname
.s3.dualstack.aws-region
.amazonaws.com -
Path-style dual-stack endpoint:
s3.dualstack.
aws-region
.amazonaws.com/bucketname
For more information, about endpoint name style, see Accessing and listing an Amazon S3 bucket . For a list of Amazon S3 endpoints, see Regions and Endpoints in the Amazon Web Services General Reference.
Important
You can use transfer acceleration with dual-stack endpoints. For more information, see Getting started with Amazon S3 Transfer Acceleration .
Note
The two types of VPC endpoints to access Amazon S3 (Interface VPC endpoints and Gateway VPC endpoints) don't have dual-stack support. For more information about VPC endpoints for Amazon S3, see Amazon PrivateLink for Amazon S3 .
When using the Amazon Command Line Interface (Amazon CLI) and Amazon SDKs, you can use a parameter or flag to change to a dual-stack endpoint. You can also specify the dual-stack endpoint directly as an override of the Amazon S3 endpoint in the config file. The following sections describe how to use dual-stack endpoints from the Amazon CLI and the Amazon SDKs.
Using dual-stack endpoints from the Amazon CLI
This section provides examples of Amazon CLI commands used to make requests to a dual-stack endpoint. For instructions on setting up the Amazon CLI, see Developing with Amazon S3 using the Amazon CLI.
You set the configuration value use_dualstack_endpoint
to
true
in a profile in your Amazon Config file to direct all Amazon S3 requests
made by the s3
and s3api
Amazon CLI commands to the dual-stack
endpoint for the specified region. You specify the region in the config file or in a
command using the --region
option.
When using dual-stack endpoints with the Amazon CLI, both path
and
virtual
addressing styles are supported. The addressing style, set in
the config file, controls if the bucket name is in the hostname or part of the URL. By
default, the CLI will attempt to use virtual style where possible, but will fall back to
path style if necessary. For more information, see Amazon CLI Amazon S3
Configuration.
You can also make configuration changes by using a command, as shown in the
following example, which sets use_dualstack_endpoint
to true
and addressing_style
to virtual
in the default profile.
$
aws configure set default.s3.use_dualstack_endpoint true$
aws configure set default.s3.addressing_style virtual
If you want to use a dual-stack endpoint for specified Amazon CLI commands only (not all commands), you can use either of the following methods:
You can use the dual-stack endpoint per command by setting the
--endpoint-url
parameter tohttps://s3.dualstack.
oraws-region
.amazonaws.comhttp://s3.dualstack.
for anyaws-region
.amazonaws.coms3
ors3api
command.$
aws s3api list-objects --bucketbucketname
--endpoint-url https://s3.dualstack.aws-region
.amazonaws.comYou can set up separate profiles in your Amazon Config file. For example, create one profile that sets
use_dualstack_endpoint
totrue
and a profile that does not setuse_dualstack_endpoint
. When you run a command, specify which profile you want to use, depending upon whether or not you want to use the dual-stack endpoint.
Note
When using the Amazon CLI you currently cannot use transfer acceleration with dual-stack endpoints. However, support for the Amazon CLI is coming soon. For more information, see Enabling and using S3 Transfer Acceleration .
Using dual-stack endpoints from the Amazon SDKs
This section provides examples of how to access a dual-stack endpoint by using the Amazon SDKs.
Amazon SDK for Java dual-stack endpoint example
The following example shows how to enable dual-stack endpoints when creating an Amazon S3 client using the Amazon SDK for Java.
For instructions on creating and testing a working Java sample, see Getting Started in the Amazon SDK for Java Developer Guide.
import com.amazonaws.AmazonServiceException; import com.amazonaws.SdkClientException; import com.amazonaws.auth.profile.ProfileCredentialsProvider; import com.amazonaws.regions.Regions; import com.amazonaws.services.s3.AmazonS3; import com.amazonaws.services.s3.AmazonS3ClientBuilder; public class DualStackEndpoints { public static void main(String[] args) { Regions clientRegion = Regions.DEFAULT_REGION; String bucketName = "*** Bucket name ***"; try { // Create an Amazon S3 client with dual-stack endpoints enabled. AmazonS3 s3Client = AmazonS3ClientBuilder.standard() .withCredentials(new ProfileCredentialsProvider()) .withRegion(clientRegion) .withDualstackEnabled(true) .build(); s3Client.listObjects(bucketName); } catch (AmazonServiceException e) { // The call was transmitted successfully, but Amazon S3 couldn't process // it, so it returned an error response. e.printStackTrace(); } catch (SdkClientException e) { // Amazon S3 couldn't be contacted for a response, or the client // couldn't parse the response from Amazon S3. e.printStackTrace(); } } }
If you are using the Amazon SDK for Java on Windows, you might have to set the following Java virtual machine (JVM) property:
java.net.preferIPv6Addresses=true
Amazon .NET SDK dual-stack endpoint example
When using the Amazon SDK for .NET you use the AmazonS3Config
class
to enable the use of a dual-stack endpoint as shown in the following example.
using Amazon; using Amazon.S3; using Amazon.S3.Model; using System; using System.Threading.Tasks; namespace Amazon.DocSamples.S3 { class DualStackEndpointTest { private const string bucketName = "*** bucket name ***"; // Specify your bucket region (an example region is shown). private static readonly RegionEndpoint bucketRegion = RegionEndpoint.USWest2; private static IAmazonS3 client; public static void Main() { var config = new AmazonS3Config { UseDualstackEndpoint = true, RegionEndpoint = bucketRegion }; client = new AmazonS3Client(config); Console.WriteLine("Listing objects stored in a bucket"); ListingObjectsAsync().Wait(); } private static async Task ListingObjectsAsync() { try { var request = new ListObjectsV2Request { BucketName = bucketName, MaxKeys = 10 }; ListObjectsV2Response response; do { response = await client.ListObjectsV2Async(request); // Process the response. foreach (S3Object entry in response.S3Objects) { Console.WriteLine("key = {0} size = {1}", entry.Key, entry.Size); } Console.WriteLine("Next Continuation Token: {0}", response.NextContinuationToken); request.ContinuationToken = response.NextContinuationToken; } while (response.IsTruncated == true); } catch (AmazonS3Exception amazonS3Exception) { Console.WriteLine("An AmazonS3Exception was thrown. Exception: " + amazonS3Exception.ToString()); } catch (Exception e) { Console.WriteLine("Exception: " + e.ToString()); } } } }
For information about setting up and running the code examples, see Getting Started with the Amazon SDK for .NET in the Amazon SDK for .NET Developer Guide.
Using dual-stack endpoints from the REST API
For information about making requests to dual-stack endpoints by using the REST API, see Making requests to dual-stack endpoints by using the REST API.