regioninfo

README

AWS Region-Specific Information Directory

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:

// Get the information for "eu-west-1":
region := regionInfo.RegionInfo_Get(jsii.String("eu-west-1"))

// Access attributes:
region.s3StaticWebsiteEndpoint // s3-website-eu-west-1.amazonaws.com
region.ServicePrincipal(jsii.String("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:

codeDeployPrincipal := regionInfo.Fact_Find(jsii.String("us-east-1"), regionInfo.FactName_ServicePrincipal(jsii.String("codedeploy.amazonaws.com")))
// => codedeploy.us-east-1.amazonaws.com

staticWebsite := regionInfo.Fact_Find(jsii.String("ap-northeast-1"), regionInfo.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:

type myFact struct {
	region
	name
	value
}

regionInfo.Fact_Register(NewMyFact())

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:

type myFact struct {
	region
	name
	value
}

regionInfo.Fact_Register(NewMyFact(), jsii.Boolean(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.

Documentation

Index

• func Default_ServicePrincipal(serviceFqn *string, region *string, urlSuffix *string) *string
• func Default_VPC_ENDPOINT_SERVICE_NAME_PREFIX() *string
• func FactName_APPMESH_ECR_ACCOUNT() *string
• func FactName_CDK_METADATA_RESOURCE_AVAILABLE() *string
• func FactName_CloudwatchLambdaInsightsVersion(version *string, arch *string) *string
• func FactName_DLC_REPOSITORY_ACCOUNT() *string
• func FactName_DOMAIN_SUFFIX() *string
• func FactName_EBS_ENV_ENDPOINT_HOSTED_ZONE_ID() *string
• func FactName_ELBV2_ACCOUNT() *string
• func FactName_FIREHOSE_CIDR_BLOCK() *string
• func FactName_PARTITION() *string
• func FactName_S3_STATIC_WEBSITE_ENDPOINT() *string
• func FactName_S3_STATIC_WEBSITE_ZONE_53_HOSTED_ZONE_ID() *string
• func FactName_ServicePrincipal(service *string) *string
• func FactName_VPC_ENDPOINT_SERVICE_NAME_PREFIX() *string
• func Fact_Find(region *string, name *string) *string
• func Fact_Regions() *[]*string
• func Fact_Register(fact IFact, allowReplacing *bool)
• func Fact_RequireFact(region *string, name *string) *string
• func Fact_Unregister(region *string, name *string, value *string)
• func NewFactName_Override(f FactName)
• func RegionInfo_LimitedRegionMap(factName *string, partitions *[]*string) *map[string]*string
• func RegionInfo_RegionMap(factName *string) *map[string]*string
• func RegionInfo_Regions() *[]RegionInfo
• type Default
• type Fact
• type FactName
  • func NewFactName() FactName
• type IFact
• type RegionInfo
  • func RegionInfo_Get(name *string) RegionInfo

Functions

func Default_ServicePrincipal

func Default_ServicePrincipal(serviceFqn *string, region *string, urlSuffix *string) *string

Computes a "standard" AWS Service principal for a given service, region and suffix.

This is useful for example when you need to compute a service principal name, but you do not have a synthesize-time region literal available (so all you have is `{ "Ref": "AWS::Region" }`). This way you get the same defaulting behavior that is normally used for built-in data. Experimental.

func Default_VPC_ENDPOINT_SERVICE_NAME_PREFIX

func Default_VPC_ENDPOINT_SERVICE_NAME_PREFIX() *string

func FactName_APPMESH_ECR_ACCOUNT

func FactName_APPMESH_ECR_ACCOUNT() *string

func FactName_CDK_METADATA_RESOURCE_AVAILABLE

func FactName_CDK_METADATA_RESOURCE_AVAILABLE() *string

func FactName_CloudwatchLambdaInsightsVersion

func FactName_CloudwatchLambdaInsightsVersion(version *string, arch *string) *string

The ARN of CloudWatch Lambda Insights for a version (e.g. 1.0.98.0). Experimental.

func FactName_DLC_REPOSITORY_ACCOUNT

func FactName_DLC_REPOSITORY_ACCOUNT() *string

func FactName_DOMAIN_SUFFIX

func FactName_DOMAIN_SUFFIX() *string

func FactName_EBS_ENV_ENDPOINT_HOSTED_ZONE_ID

func FactName_EBS_ENV_ENDPOINT_HOSTED_ZONE_ID() *string

func FactName_ELBV2_ACCOUNT

func FactName_ELBV2_ACCOUNT() *string

func FactName_FIREHOSE_CIDR_BLOCK

func FactName_FIREHOSE_CIDR_BLOCK() *string

func FactName_PARTITION

func FactName_PARTITION() *string

func FactName_S3_STATIC_WEBSITE_ENDPOINT

func FactName_S3_STATIC_WEBSITE_ENDPOINT() *string

func FactName_S3_STATIC_WEBSITE_ZONE_53_HOSTED_ZONE_ID

func FactName_S3_STATIC_WEBSITE_ZONE_53_HOSTED_ZONE_ID() *string

func FactName_ServicePrincipal

func FactName_ServicePrincipal(service *string) *string

The name of the regional service principal for a given service. Experimental.

func FactName_VPC_ENDPOINT_SERVICE_NAME_PREFIX

func FactName_VPC_ENDPOINT_SERVICE_NAME_PREFIX() *string

func Fact_Find

func Fact_Find(region *string, name *string) *string

Retrieves a fact from this Fact database.

Returns: the fact value if it is known, and `undefined` otherwise. Experimental.

func Fact_Regions

func Fact_Regions() *[]*string

func Fact_Register

func Fact_Register(fact IFact, allowReplacing *bool)

Registers a new fact in this Fact database. Experimental.

func Fact_RequireFact

func Fact_RequireFact(region *string, name *string) *string

Retrieve a fact from the Fact database.

(retrieval will fail if the specified region or fact name does not exist.) Experimental.

func Fact_Unregister

func Fact_Unregister(region *string, name *string, value *string)

Removes a fact from the database. Experimental.

func NewFactName_Override

func NewFactName_Override(f FactName)

Experimental.

func RegionInfo_LimitedRegionMap

func RegionInfo_LimitedRegionMap(factName *string, partitions *[]*string) *map[string]*string

Retrieves a collection of all fact values for all regions, limited to some partitions.

Returns: a mapping with AWS region codes as the keys, and the fact in the given region as the value for that key. Experimental.

func RegionInfo_RegionMap

func RegionInfo_RegionMap(factName *string) *map[string]*string

Retrieves a collection of all fact values for all regions that fact is defined in.

Returns: a mapping with AWS region codes as the keys, and the fact in the given region as the value for that key. Experimental.

func RegionInfo_Regions

func RegionInfo_Regions() *[]RegionInfo

Types

type Default

type Default interface {
}

Provides default values for certain regional information points. Experimental.

type Fact

type Fact interface {
}

A database of regional information.

Example:

type myFact struct {
	region
	name
	value
}

regionInfo.Fact_Register(NewMyFact())

Experimental.

type FactName

type FactName interface {
}

All standardized fact names.

Example:

type myFact struct {
	region
	name
	value
}

regionInfo.Fact_Register(NewMyFact())

Experimental.

func NewFactName

func NewFactName() FactName

Experimental.

type IFact

type IFact interface {
	// The name of this fact.
	//
	// Standardized values are provided by the `Facts` class.
	// Experimental.
	Name() *string
	// The region for which this fact applies.
	// Experimental.
	Region() *string
	// The value of this fact.
	// Experimental.
	Value() *string
}

A fact that can be registered about a particular region. Experimental.

type RegionInfo

type RegionInfo interface {
	// The ID of the AWS account that owns the public ECR repository that contains the AWS App Mesh Envoy Proxy images in a given region.
	// Experimental.
	AppMeshRepositoryAccount() *string
	// Whether the `AWS::CDK::Metadata` CloudFormation Resource is available in this region or not.
	// Experimental.
	CdkMetadataResourceAvailable() *bool
	// The ID of the AWS account that owns the public ECR repository containing the AWS Deep Learning Containers images in this region.
	// Experimental.
	DlcRepositoryAccount() *string
	// The domain name suffix (e.g: amazonaws.com) for this region.
	// Experimental.
	DomainSuffix() *string
	// The hosted zone ID used by Route 53 to alias a EBS environment endpoint in this region (e.g: Z2O1EMRO9K5GLX).
	// Experimental.
	EbsEnvEndpointHostedZoneId() *string
	// The account ID for ELBv2 in this region.
	// Experimental.
	Elbv2Account() *string
	// The CIDR block used by Kinesis Data Firehose servers.
	// Experimental.
	FirehoseCidrBlock() *string
	// Experimental.
	Name() *string
	// The name of the ARN partition for this region (e.g: aws).
	// Experimental.
	Partition() *string
	// The endpoint used by S3 static website hosting in this region (e.g: s3-static-website-us-east-1.amazonaws.com).
	// Experimental.
	S3StaticWebsiteEndpoint() *string
	// The hosted zone ID used by Route 53 to alias a S3 static website in this region (e.g: Z2O1EMRO9K5GLX).
	// Experimental.
	S3StaticWebsiteHostedZoneId() *string
	// The prefix for VPC Endpoint Service names, cn.com.amazonaws.vpce for China regions, com.amazonaws.vpce otherwise.
	// Experimental.
	VpcEndpointServiceNamePrefix() *string
	// The ARN of the CloudWatch Lambda Insights extension, for the given version.
	// Experimental.
	CloudwatchLambdaInsightsArn(insightsVersion *string, architecture *string) *string
	// The name of the service principal for a given service in this region.
	// Experimental.
	ServicePrincipal(service *string) *string
}

Information pertaining to an AWS region.

Example:

// Get the information for "eu-west-1":
region := regionInfo.RegionInfo_Get(jsii.String("eu-west-1"))

// Access attributes:
region.s3StaticWebsiteEndpoint // s3-website-eu-west-1.amazonaws.com
region.ServicePrincipal(jsii.String("logs.amazonaws.com"))

Experimental.

func RegionInfo_Get

func RegionInfo_Get(name *string) RegionInfo

Obtain region info for a given region name. Experimental.