aws-cdk.region-info 1.27.0

AWS region information, such as service principal names

AWS Region-Specific Information Directory

---

This is a developer preview (public beta) module.

All classes with the Cfn prefix in this module (CFN Resources) are auto-generated from CloudFormation. They are stable and safe to use.

However, all other classes, i.e., higher level constructs, are under active development and subject to non-backward compatible changes or removal in any future version. These are not subject to the Semantic Versioning model. 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:

# Example automatically generated. See https://github.com/aws/jsii/issues/826
from aws_cdk.region_info import RegionInfo

# Get the information for "eu-west-1":
region = RegionInfo.get("eu-west-1")

# Access attributes:
region.s3_static_website_endpoint# s3-website-eu-west-1.amazonaws.com
region.service_principal("logs.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:

# Example automatically generated. See https://github.com/aws/jsii/issues/826
import aws_cdk.region_info as region_info

code_deploy_principal = region_info.Fact.find("us-east-1", region_info.FactName.service_principal("codedeploy.amazonaws.com"))
# => codedeploy.us-east-1.amazonaws.com

static_website = region_info.Fact.find("ap-northeast-1", region_info.FactName.S3_STATIC_WEBSITE_ENDPOINT)

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:

# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
region_info.Fact.register(
    region="bermuda-triangle-1",
    name=region_info.FactName.service_principal("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:

# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
region_info.Fact.register({
    "region": "us-east-1",
    "name": region_info.FactName.service_principal("service.amazonaws.com"),
    "value": "the-correct-principal.amazonaws.com"
}, True)

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.