Tag: regions

Using New Regions and Endpoints

by Jeremy Lindblom | on | in PHP | Permalink | Comments |  Share

Last week, a customer asked us how they could configure the AWS SDK for PHP to use Amazon SES with the EU (Ireland) Region. SES had just released support for the EU Region, but there was no tagged version of the SDK that supported it yet.

Our typical process is to push new support for regions to the master branch of the AWS SDK for PHP repository as soon as possible after they are announced. In fact, at the time that the customer asked us about EU Region support in SES, we had already pushed out support for it. However, if you are using only tagged versions of the SDK, which you should do with production code, then you may have to wait 1 or 2 weeks until a new version of the SDK is released.

Configuring the base URL of your client

Fortunately, there is a way to use new regions and endpoints, even if the SDK does not yet support a new region for a service. You can manually configure the base_url of a client when you instantiate it. For example, to configure an SES client to use the EU Region, do the following:

$ses = AwsSesSesClient::factory(array(
    'key'      => 'YOUR_AWS_ACCESS_KEY_ID',
    'secret'   => 'YOUR_AWS_SECRET_KEY',
    'region'   => 'eu-west-1',
    'base_url' => 'https://email.eu-west-1.amazonaws.com',

Remember, you only need to specify the base_url if the SDK doesn’t already support the region. For regions that the SDK does support, the endpoint is automatically determined.

To find the correct URL to use for your desired service and region, see the Regions and Endpoints page of the AWS General Reference documentation.

Using the base_url for other reasons

The base_url option can be used for more than just accessing new regions. It can be used to allow the SDK to send requests to any endpoint compatible with the API of the service you are using (e.g., mock/test services, private beta endpoints).

An example of this is the DynamoDB Local tool that acts as a small client-side database and server that mimics Amazon DynamoDB. You can easily configure a DynamoDB client to work with DynamoDB Local by using the base_url option (assuming you have correctly installed and started DynamoDB Local).

$dynamodb = AwsDynamoDbDynamoDbClient::factory(array(
    'key'      => 'YOUR_AWS_ACCESS_KEY_ID',
    'secret'   => 'YOUR_AWS_SECRET_KEY',
    'region'   => 'us-east-1',
    'base_url' => 'http://localhost:8000',

For more information, see Setting a custom endpoint in the AWS SDK for PHP User Guide.

Using the latest SDK via Composer

If you are using Composer with the SDK, then you have another option for picking up new features, like newly supported regions, without modifying your code. If you need to use a new feature or bugfix that is not yet in a tagged release, you can do so by adjusting the SDK dependency in your composer.json file to use our development alias 2.5.x-dev.

    "require": {
        "aws/aws-sdk-php": "2.5.x-dev"

Using the development alias, instead of dev-master, is ideal, because if you have other dependencies that require the SDK, version constraints like "2.5.*" will still resolve correctly. Remember that relying on a non-tagged version of the SDK is not recommended for production code.

Working with Multiple Regions

by Trevor Rowe | on | in Ruby | Permalink | Comments |  Share

In a previous blog post, I introduced the new :region configuration option for the AWS SDK for Ruby (aws-sdk gem). Beyond simplified configuration, the Ruby SDK provides additional helpers for working with multiple regions.

There are two new helper classes for working with regions, AWS::Core::Region and AWS::Core::RegionCollection. The AWS module provides helper methods so that you should not need to instantiate these classes directly.

Region Objects

If you know the name of a region you need to work with, you can create it like so:

# no HTTP request required, simply returns a new AWS::Core::Region object
region = AWS.regions['us-west-2']

A region object provides access to service interface objects. Every service can be accessed using its short name.

region = AWS.regions['us-west-2']

# collect the ids of instances running in this region

# collect the name of tables created in this region

See the Region class API documentation for a complete list of service interface helper methods.


Besides returning a single region object, the region collection can also enumerate all public (non GovCloud) regions.

AWS.regions.each do |region|
  puts region.name

Please note that when you enumerate regions, an HTTP request is made to get a current list of regions and services. The response is cached for the life of the process.

Enumerating Regions from a Service

Not all services are available in every region. You can safely enumerate only regions a service operates in using a region collection from a service interface. In the following example we use the regions helper method to enumerate what regions Amazon DynamoDB and Amazon Redshift operate in.

#=> ["us-east-1", "us-west-1", "us-west-2", "eu-west-1", "ap-northeast-1", "ap-southeast-1", "ap-southeast-2", "sa-east-1"] 

#=> ["us-east-1", "us-west-2", "eu-west-1"] 

You can use the region object to operate on a service resource in each region it exists in. As a service expands to additional regions, you code will automatically include those regions when enumerating. In the following example, we list all of the Amazon DynamoDB tables, grouped by region.

# generate a list of DynamoDB tables for every region
AWS::DynamoDB.regions.each do |region|
  table_names = region.dynamo_db.tables.map(&:name)
  unless table_names.empty?
    puts "Region: " + region.name
    puts "Tables:"
    puts table_names.join("n")
    puts ""

Take the new regions interfaces for a spin and let us know what you think!

Working with Regions

by Trevor Rowe | on | in Ruby | Permalink | Comments |  Share

The AWS SDK for Ruby (aws-sdk gem) has some cool new features that simplify working with regions.

The Ruby SDK defaults to the us-east-1 region for all services. Until recently, you had to specify the full regional endpoint for each service you connect to outside the default region. If you use multiple services outside us-east-1, this can be a pain. Your code might end up looking like this:

  ec2_endpoint: 'ec2.us-west-2.amazonaws.com',
  s3_endpoint: 's3-us-west-2.amazonaws.com',
  # and so on ...

Region to the Rescue

You can now set the default region for all services with a single configuration option. Services will construct their own regional endpoint from the default region. If you want to do all of your work in us-west-2, the example above would now look like this:

AWS.config(region: 'us-west-2')

You can pass the :region endpoint directly to a service interface. This is helpful if you need to connect to multiple regional endpoints for a single service.

s3_east = AWS::S3.new(region: 'us-east-1')
s3_west = AWS::S3.new(region: 'us-west-2')


The service specific endpoint options are all now deprecated. They will continue to be supported until removal in our next major revision of the Ruby SDK. The deprecated options are (replace svc with a service prefix like ec2, s3, etc):

  • :svc_endpoint
  • :svc_port
  • :svc_region

Here are a few examples of how to upgrade from the deprecated configuration options to the new options:

# service prefixed connection options are deprecated with AWS.config
AWS.config(s3_endpoint: 'localhost', s3_port: 8000)
s3 = AWS::S3::Client.new

# service prefixed connection options are deprecated with clients
s3 = AWS::S3::Client.new(s3_endpoint: 'localhost', s3_port: 8000)

# this is the preferred method for setting endpoint and port
s3 = AWS::S3::Client.new(endpoint: 'localhost', port: 8000)