Use DescribeRegions with an Amazon SDK or CLI - Amazon Elastic Compute Cloud
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 DescribeRegions with an Amazon SDK or CLI

The following code examples show how to use DescribeRegions.

C++
SDK for C++
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository.

//! Describe all Amazon Elastic Compute Cloud (Amazon EC2) Regions. /*! \param clientConfiguration: AWS client configuration. \return bool: Function succeeded. */ bool AwsDoc::EC2::describeRegions( const Aws::Client::ClientConfiguration &clientConfiguration) { Aws::EC2::EC2Client ec2Client(clientConfiguration); Aws::EC2::Model::DescribeRegionsRequest request; Aws::EC2::Model::DescribeRegionsOutcome outcome = ec2Client.DescribeRegions(request); if (outcome.IsSuccess()) { std::cout << std::left << std::setw(32) << "RegionName" << std::setw(64) << "Endpoint" << std::endl; const auto &regions = outcome.GetResult().GetRegions(); for (const auto &region: regions) { std::cout << std::left << std::setw(32) << region.GetRegionName() << std::setw(64) << region.GetEndpoint() << std::endl; } } else { std::cerr << "Failed to describe regions:" << outcome.GetError().GetMessage() << std::endl; } std::cout << std::endl; return outcome.IsSuccess(); }
  • For API details, see DescribeRegions in Amazon SDK for C++ API Reference.

CLI
Amazon CLI

Example 1: To describe all of your enabled Regions

The following describe-regions example describes all of the Regions that are enabled for your account.

aws ec2 describe-regions

Output:

{ "Regions": [ { "Endpoint": "ec2.eu-north-1.amazonaws.com", "RegionName": "eu-north-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.ap-south-1.amazonaws.com", "RegionName": "ap-south-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.eu-west-3.amazonaws.com", "RegionName": "eu-west-3", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.eu-west-2.amazonaws.com", "RegionName": "eu-west-2", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.eu-west-1.amazonaws.com", "RegionName": "eu-west-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.ap-northeast-3.amazonaws.com", "RegionName": "ap-northeast-3", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.ap-northeast-2.amazonaws.com", "RegionName": "ap-northeast-2", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.ap-northeast-1.amazonaws.com", "RegionName": "ap-northeast-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.sa-east-1.amazonaws.com", "RegionName": "sa-east-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.ca-central-1.amazonaws.com", "RegionName": "ca-central-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.ap-southeast-1.amazonaws.com", "RegionName": "ap-southeast-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.ap-southeast-2.amazonaws.com", "RegionName": "ap-southeast-2", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.eu-central-1.amazonaws.com", "RegionName": "eu-central-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.us-east-1.amazonaws.com", "RegionName": "us-east-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.us-east-2.amazonaws.com", "RegionName": "us-east-2", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.us-west-1.amazonaws.com", "RegionName": "us-west-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.us-west-2.amazonaws.com", "RegionName": "us-west-2", "OptInStatus": "opt-in-not-required" } ] }

For more information, see Regions and Zones in the Amazon EC2 User Guide.

Example 2: To describe enabled Regions with an endpoint whose name contains a specific string

The following describe-regions example describes all Regions that you have enabled that have the string "us" in the endpoint.

aws ec2 describe-regions \ --filters "Name=endpoint,Values=*us*"

Output:

{ "Regions": [ { "Endpoint": "ec2.us-east-1.amazonaws.com", "RegionName": "us-east-1" }, { "Endpoint": "ec2.us-east-2.amazonaws.com", "RegionName": "us-east-2" }, { "Endpoint": "ec2.us-west-1.amazonaws.com", "RegionName": "us-west-1" }, { "Endpoint": "ec2.us-west-2.amazonaws.com", "RegionName": "us-west-2" } ] }

For more information, see Regions and Zones in the Amazon EC2 User Guide.

Example 3: To describe all Regions

The following describe-regions example describes all available Regions, including Regions that are disabled.

aws ec2 describe-regions \ --all-regions

Output:

{ "Regions": [ { "Endpoint": "ec2.eu-north-1.amazonaws.com", "RegionName": "eu-north-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.ap-south-1.amazonaws.com", "RegionName": "ap-south-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.eu-west-3.amazonaws.com", "RegionName": "eu-west-3", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.eu-west-2.amazonaws.com", "RegionName": "eu-west-2", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.eu-west-1.amazonaws.com", "RegionName": "eu-west-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.ap-northeast-3.amazonaws.com", "RegionName": "ap-northeast-3", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.me-south-1.amazonaws.com", "RegionName": "me-south-1", "OptInStatus": "not-opted-in" }, { "Endpoint": "ec2.ap-northeast-2.amazonaws.com", "RegionName": "ap-northeast-2", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.ap-northeast-1.amazonaws.com", "RegionName": "ap-northeast-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.sa-east-1.amazonaws.com", "RegionName": "sa-east-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.ca-central-1.amazonaws.com", "RegionName": "ca-central-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.ap-east-1.amazonaws.com", "RegionName": "ap-east-1", "OptInStatus": "not-opted-in" }, { "Endpoint": "ec2.ap-southeast-1.amazonaws.com", "RegionName": "ap-southeast-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.ap-southeast-2.amazonaws.com", "RegionName": "ap-southeast-2", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.eu-central-1.amazonaws.com", "RegionName": "eu-central-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.us-east-1.amazonaws.com", "RegionName": "us-east-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.us-east-2.amazonaws.com", "RegionName": "us-east-2", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.us-west-1.amazonaws.com", "RegionName": "us-west-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.us-west-2.amazonaws.com", "RegionName": "us-west-2", "OptInStatus": "opt-in-not-required" } ] }

For more information, see Regions and Zones in the Amazon EC2 User Guide.

Example 4: To list the Region names only

The following describe-regions example uses the --query parameter to filter the output and return only the names of the Regions as text.

aws ec2 describe-regions \ --all-regions \ --query "Regions[].{Name:RegionName}" \ --output text

Output:

eu-north-1 ap-south-1 eu-west-3 eu-west-2 eu-west-1 ap-northeast-3 ap-northeast-2 me-south-1 ap-northeast-1 sa-east-1 ca-central-1 ap-east-1 ap-southeast-1 ap-southeast-2 eu-central-1 us-east-1 us-east-2 us-west-1 us-west-2

For more information, see Regions and Zones in the Amazon EC2 User Guide.

JavaScript
SDK for JavaScript (v3)
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository.

import { DescribeRegionsCommand, EC2Client } from "@aws-sdk/client-ec2"; /** * List all available AWS regions. * @param {{ regionNames: string[], includeOptInRegions: boolean }} options */ export const main = async ({ regionNames, includeOptInRegions }) => { const client = new EC2Client({}); const command = new DescribeRegionsCommand({ // By default this command will not show regions that require you to opt-in. // When AllRegions is true, even the regions that require opt-in will be returned. AllRegions: includeOptInRegions, // You can omit the Filters property if you want to get all regions. Filters: regionNames?.length ? [ { Name: "region-name", // You can specify multiple values for a filter. // You can also use '*' as a wildcard. This will return all // of the regions that start with `us-east-`. Values: regionNames, }, ] : undefined, }); try { const { Regions } = await client.send(command); const regionsList = Regions.map((reg) => ` • ${reg.RegionName}`); console.log("Found regions:"); console.log(regionsList.join("\n")); } catch (caught) { if (caught instanceof Error && caught.name === "DryRunOperation") { console.log(`${caught.message}`); } else { throw caught; } } };
  • For API details, see DescribeRegions in Amazon SDK for JavaScript API Reference.

PowerShell
Tools for PowerShell

Example 1: This example describes the regions that are available to you.

Get-EC2Region

Output:

Endpoint RegionName -------- ---------- ec2.eu-west-1.amazonaws.com eu-west-1 ec2.ap-southeast-1.amazonaws.com ap-southeast-1 ec2.ap-southeast-2.amazonaws.com ap-southeast-2 ec2.eu-central-1.amazonaws.com eu-central-1 ec2.ap-northeast-1.amazonaws.com ap-northeast-1 ec2.us-east-1.amazonaws.com us-east-1 ec2.sa-east-1.amazonaws.com sa-east-1 ec2.us-west-1.amazonaws.com us-west-1 ec2.us-west-2.amazonaws.com us-west-2
  • For API details, see DescribeRegions in Amazon Tools for PowerShell Cmdlet Reference.

Ruby
SDK for Ruby
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository.

require 'aws-sdk-ec2' # @param ec2_client [Aws::EC2::Client] An initialized EC2 client. # @example # list_regions_endpoints(Aws::EC2::Client.new(region: 'us-west-2')) def list_regions_endpoints(ec2_client) result = ec2_client.describe_regions # Enable pretty printing. max_region_string_length = 16 max_endpoint_string_length = 33 # Print header. print 'Region' print ' ' * (max_region_string_length - 'Region'.length) print " Endpoint\n" print '-' * max_region_string_length print ' ' print '-' * max_endpoint_string_length print "\n" # Print Regions and their endpoints. result.regions.each do |region| print region.region_name print ' ' * (max_region_string_length - region.region_name.length) print ' ' print region.endpoint print "\n" end end # Displays a list of Amazon Elastic Compute Cloud (Amazon EC2) # Availability Zones available to you depending on the AWS Region # of the Amazon EC2 client. # # @param ec2_client [Aws::EC2::Client] An initialized EC2 client. # @example # list_availability_zones(Aws::EC2::Client.new(region: 'us-west-2')) def list_availability_zones(ec2_client) result = ec2_client.describe_availability_zones # Enable pretty printing. max_region_string_length = 16 max_zone_string_length = 18 max_state_string_length = 9 # Print header. print 'Region' print ' ' * (max_region_string_length - 'Region'.length) print ' Zone' print ' ' * (max_zone_string_length - 'Zone'.length) print " State\n" print '-' * max_region_string_length print ' ' print '-' * max_zone_string_length print ' ' print '-' * max_state_string_length print "\n" # Print Regions, Availability Zones, and their states. result.availability_zones.each do |zone| print zone.region_name print ' ' * (max_region_string_length - zone.region_name.length) print ' ' print zone.zone_name print ' ' * (max_zone_string_length - zone.zone_name.length) print ' ' print zone.state # Print any messages for this Availability Zone. if zone.messages.count.positive? print "\n" puts ' Messages for this zone:' zone.messages.each do |message| print " #{message.message}\n" end end print "\n" end end # Example usage: def run_me region = '' # Print usage information and then stop. if ARGV[0] == '--help' || ARGV[0] == '-h' puts 'Usage: ruby ec2-ruby-example-regions-availability-zones.rb REGION' # Replace us-west-2 with the AWS Region you're using for Amazon EC2. puts 'Example: ruby ec2-ruby-example-regions-availability-zones.rb us-west-2' exit 1 # If no values are specified at the command prompt, use these default values. # Replace us-west-2 with the AWS Region you're using for Amazon EC2. elsif ARGV.count.zero? region = 'us-west-2' # Otherwise, use the values as specified at the command prompt. else region = ARGV[0] end ec2_client = Aws::EC2::Client.new(region: region) puts 'AWS Regions for Amazon EC2 that are available to you:' list_regions_endpoints(ec2_client) puts "\n\nAmazon EC2 Availability Zones that are available to you for AWS Region '#{region}':" list_availability_zones(ec2_client) end run_me if $PROGRAM_NAME == __FILE__
  • For API details, see DescribeRegions in Amazon SDK for Ruby API Reference.

Rust
SDK for Rust
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository.

async fn show_regions(client: &Client) -> Result<(), Error> { let rsp = client.describe_regions().send().await?; println!("Regions:"); for region in rsp.regions() { println!(" {}", region.region_name().unwrap()); } Ok(()) }
  • For API details, see DescribeRegions in Amazon SDK for Rust API reference.

SAP ABAP
SDK for SAP ABAP
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository.

TRY. oo_result = lo_ec2->describeregions( ) . " oo_result is returned for testing purposes. " DATA(lt_regions) = oo_result->get_regions( ). MESSAGE 'Retrieved information about Regions.' TYPE 'I'. CATCH /aws1/cx_rt_service_generic INTO DATA(lo_exception). DATA(lv_error) = |"{ lo_exception->av_err_code }" - { lo_exception->av_err_msg }|. MESSAGE lv_error TYPE 'E'. ENDTRY.
  • For API details, see DescribeRegions in Amazon SDK for SAP ABAP API reference.

For a complete list of Amazon SDK developer guides and code examples, see Create Amazon EC2 resources using an Amazon SDK. This topic also includes information about getting started and details about previous SDK versions.