Use Amazon Web Services Regions - Amazon SDK for Java 2.x
Explicitly configure an Amazon Web Services RegionDetermine Region from environmentCheck for service availabilityChoose a specific endpoint
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Use Amazon Web Services Regions

Amazon Web Services Regions enable service clients to access Amazon Web Services services that physically resides in a specific geographic area.

Explicitly configure an Amazon Web Services Region

To explicitly set a Region, we recommend that you use the constants defined in the Region class. This is an enumeration of all publicly available regions.

To create a client with an enumerated Region from the class, use the client builder's region method.

Ec2Client ec2 = Ec2Client.builder()
          .region(Region.US_WEST_2)
          .build();

If the Region you want to use isn’t one of the enumerations in the Region class, you can create a new Region by using the static of method. This method allows you access to new Regions without upgrading the SDK. 

Region newRegion = Region.of("us-east-42");
Ec2Client ec2 = Ec2Client.builder()
          .region(newRegion)
          .build();
Note

After you build a client with the builder, it’s immutable and the Amazon Web Services Region cannot be changed. If you need to work with multiple Amazon Web Services Regions for the same service, you should create multiple clients—​one per Region.

Let the SDK automatically determine the Region from the environment

When your code runs on Amazon EC2 or Amazon Lambda, you might want to configure clients to use the same Amazon Web Services Region that your code is running on. This decouples your code from the environment it’s running in and makes it easier to deploy your application to multiple Amazon Web Services Regions for lower latency or redundancy.

To use the default credential/region provider chain to determine the Region from the environment, use the client builder’s create method.

Ec2Client ec2 = Ec2Client.create();

If you don’t explicitly set an Amazon Web Services Region by using the region method, the SDK consults the default region provider chain to determine the Region to use.

Understand the default region provider chain

The SDK takes the following steps to look for an Amazon Web Services Region :

  1. Any explicit Region set by using region on the builder itself takes precedence over anything else.

  2. The AWS_REGION environment variable is checked. If it’s set, that Region is used to configure the client.

    Note

    The Lambda container sets this environment variable.

  3. The SDK checks the Amazon shared configuration file and shared credentials file (usually located at ~/.aws/config and ~/.aws/credentials). If the region property is present, the SDK uses it.

    • If the SDK finds the region property in both files for the same profile (including the default profile), the SDK uses the value in the shared credentials file.

    • The AWS_CONFIG_FILE environment variable can be used to customize the location of the shared config file.

    • The AWS_PROFILE environment variable or the aws.profile system property can be used to specify the profile that the SDK loads.

  4. The SDK attempts to use the Amazon EC2 instance metadata service (IMDS) to determine the Region of the currently running Amazon EC2 instance.

    • For greater security, you should disable the SDK from attempting to use version 1 of IMDS. You use the same setting to disable version 1 that are described in the Securely acquire IAM role credentials section.

  5. If the SDK still hasn’t found a Region by this point, client creation fails with an exception.

When developing Amazon applications, a common approach is to use the shared configuration file (described in Credential retrieval order) to set the Region for local development, and rely on the default region provider chain to determine the Region when the application runs on Amazon infrastructure. This greatly simplifies client creation and keeps your application portable.

Check for service availability in a Region

To see if a particular Amazon Web Services service is available in a Region, use the serviceMetadata and region method on the service client.

DynamoDbClient.serviceMetadata().regions().forEach(System.out::println);

See the Region class documentation for the Amazon Web Services Regions you can specify, and use the endpoint prefix of the service to query.

Choose a specific endpoint

In certain situations—such as to test preview features of a service before the features graduate to general availability—you may need to specify a specific endpoint in a Region. In these situations, service clients can be configured by calling the endpointOverride method.

For example, to configure an Amazon EC2 client to use the Europe (Ireland) Region with a specific endpoint, use the following code.

Ec2Client ec2 = Ec2Client.builder()
               .region(Region.EU_WEST_1)
               .endpointOverride(URI.create("https://ec2.eu-west-1.amazonaws.com"))
               .build();

See Regions and Endpoints for the current list of regions and their corresponding endpoints for all Amazon services.