@aws-cdk/region-info

What is @aws-cdk/region-info?

@aws-cdk/region-info is an AWS CDK library that provides information about AWS regions and services. It allows developers to programmatically access details about AWS regions, such as the services available in each region, region names, and partition information.

What are @aws-cdk/region-info's main functionalities?

Get Region Information

This feature allows you to get information about a specific AWS region. In this example, it retrieves the name of the 'us-east-1' region.

const regionInfo = require('@aws-cdk/region-info');
const region = regionInfo.RegionInfo.get('us-east-1');
console.log(region.name); // Output: US East (N. Virginia)

Check if a Service is Available in a Region

This feature allows you to check if a specific AWS service is available in a given region. In this example, it checks if the S3 service is available in the 'us-east-1' region.

const regionInfo = require('@aws-cdk/region-info');
const region = regionInfo.RegionInfo.get('us-east-1');
const isAvailable = region.servicePrincipal('s3') !== undefined;
console.log(isAvailable); // Output: true

Get Partition Information

This feature allows you to get the partition information for a specific region. In this example, it retrieves the partition for the 'us-east-1' region, which is 'aws'.

const regionInfo = require('@aws-cdk/region-info');
const partition = regionInfo.RegionInfo.get('us-east-1').partition;
console.log(partition); // Output: aws

Other packages similar to @aws-cdk/region-info

aws-sdk

The aws-sdk package is the official AWS SDK for JavaScript. It provides a comprehensive set of tools for interacting with AWS services, including region and service information. However, it is more general-purpose and not as focused on region-specific information as @aws-cdk/region-info.

aws-regions

The aws-regions package provides a list of AWS regions and their associated information. It is similar to @aws-cdk/region-info but is more lightweight and does not integrate with the AWS CDK.

README

AWS Region-Specific Information Directory

---

The APIs of higher level constructs in this module are experimental and under active development. They are subject to non-backward compatible changes or removal in any future version. These are not subject to the Semantic Versioning model and breaking changes will be announced in the release notes. This means that while you may use them, you may need to update your source code when upgrading to a newer version of this package.

---

Usage

Some information used in CDK Applications differs from one AWS region to another, such as service principals used in IAM policies, S3 static website endpoints, ...

The RegionInfo class

The library offers a simple interface to obtain region specific information in the form of the RegionInfo class. This is the preferred way to interact with the regional information database:

import { RegionInfo } from '@aws-cdk/region-info';

// Get the information for "eu-west-1":
const region = RegionInfo.get('eu-west-1');

// Access attributes:
region.s3StaticWebsiteEndpoint; // s3-website-eu-west-1.amazonaws.com
region.servicePrincipal('logs.amazonaws.com'); // logs.eu-west-1.amazonaws.com

The RegionInfo layer is built on top of the Low-Level API, which is described below and can be used to register additional data, including user-defined facts that are not available through the RegionInfo interface.

Low-Level API

This library offers a primitive database of such information so that CDK constructs can easily access regional information. The FactName class provides a list of known fact names, which can then be used with the RegionInfo to retrieve a particular value:

import * as regionInfo from '@aws-cdk/region-info';

const codeDeployPrincipal = regionInfo.Fact.find('us-east-1', regionInfo.FactName.servicePrincipal('codedeploy.amazonaws.com'));
// => codedeploy.us-east-1.amazonaws.com

const staticWebsite = regionInfo.Fact.find('ap-northeast-1', regionInfo.FactName.S3_STATIC_WEBSITE_ENDPOINT);
// => s3-website-ap-northeast-1.amazonaws.com

Supplying new or missing information

As new regions are released, it might happen that a particular fact you need is missing from the library. In such cases, the Fact.register method can be used to inject FactName into the database:

regionInfo.Fact.register({
  region: 'bermuda-triangle-1',
  name: regionInfo.FactName.servicePrincipal('s3.amazonaws.com'),
  value: 's3-website.bermuda-triangle-1.nowhere.com',
});

Overriding incorrect information

In the event information provided by the library is incorrect, it can be overridden using the same Fact.register method demonstrated above, simply adding an extra boolean argument:

regionInfo.Fact.register({
  region: 'us-east-1',
  name: regionInfo.FactName.servicePrincipal('service.amazonaws.com'),
  value: 'the-correct-principal.amazonaws.com',
}, true /* Allow overriding information */);

If you happen to have stumbled upon incorrect data built into this library, it is always a good idea to report your findings in a GitHub issue, so we can fix it for everyone else!

---

This module is part of the AWS Cloud Development Kit project.