{ "author": { "name": "Amazon Web Services", "organization": true, "roles": [ "author" ], "url": "https://aws.amazon.com" }, "description": "AWS region information, such as service principal names", "docs": { "stability": "experimental" }, "homepage": "https://github.com/aws/aws-cdk", "jsiiVersion": "1.12.0 (build 5ddc9f2)", "keywords": [ "aws", "cdk" ], "license": "Apache-2.0", "name": "@aws-cdk/region-info", "readme": { "markdown": "# AWS Region-Specific Information Directory\n\n---\n\n![cdk-constructs: Experimental](https://img.shields.io/badge/cdk--constructs-experimental-important.svg?style=for-the-badge)\n\n> 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](https://semver.org/) 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.\n\n---\n\n\n## Usage\nSome information used in CDK Applications differs from one AWS region to\nanother, such as service principals used in IAM policies, S3 static website\nendpoints, ...\n\n### The `RegionInfo` class\nThe library offers a simple interface to obtain region specific information in\nthe form of the `RegionInfo` class. This is the preferred way to interact with\nthe regional information database:\n\n```ts\nimport { RegionInfo } from '@aws-cdk/region-info';\n\n// Get the information for \"eu-west-1\":\nconst region = RegionInfo.get('eu-west-1');\n\n// Access attributes:\nregion.s3StaticWebsiteEndpoint; // s3-website-eu-west-1.amazonaws.com\nregion.servicePrincipal('logs.amazonaws.com'); // logs.eu-west-1.amazonaws.com\n```\n\nThe `RegionInfo` layer is built on top of the Low-Level API, which is described\nbelow and can be used to register additional data, including user-defined facts\nthat are not available through the `RegionInfo` interface.\n\n### Low-Level API\nThis library offers a primitive database of such information so that CDK\nconstructs can easily access regional information. The `FactName` class provides\na list of known fact names, which can then be used with the `RegionInfo` to\nretrieve a particular value:\n\n```ts\nimport * as regionInfo from '@aws-cdk/region-info';\n\nconst codeDeployPrincipal = regionInfo.Fact.find('us-east-1', regionInfo.FactName.servicePrincipal('codedeploy.amazonaws.com'));\n// => codedeploy.us-east-1.amazonaws.com\n\nconst staticWebsite = regionInfo.Fact.find('ap-northeast-1', regionInfo.FactName.S3_STATIC_WEBSITE_ENDPOINT);\n// => s3-website-ap-northeast-1.amazonaws.com\n```\n\n## Supplying new or missing information\nAs new regions are released, it might happen that a particular fact you need is\nmissing from the library. In such cases, the `Fact.register` method can be used\nto inject FactName into the database:\n\n```ts\nregionInfo.Fact.register({\n region: 'bermuda-triangle-1',\n name: regionInfo.FactName.servicePrincipal('s3.amazonaws.com'),\n value: 's3-website.bermuda-triangle-1.nowhere.com',\n});\n```\n\n## Overriding incorrect information\nIn the event information provided by the library is incorrect, it can be\noverridden using the same `Fact.register` method demonstrated above, simply\nadding an extra boolean argument:\n\n```ts\nregionInfo.Fact.register({\n region: 'us-east-1',\n name: regionInfo.FactName.servicePrincipal('service.amazonaws.com'),\n value: 'the-correct-principal.amazonaws.com',\n}, true /* Allow overriding information */);\n```\n\nIf you happen to have stumbled upon incorrect data built into this library, it\nis always a good idea to report your findings in a [GitHub issue], so we can fix\nit for everyone else!\n\n[GitHub issue]: https://github.com/aws/aws-cdk/issues\n\n---\n\nThis module is part of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) project.\n" }, "repository": { "directory": "packages/@aws-cdk/region-info", "type": "git", "url": "https://github.com/aws/aws-cdk.git" }, "schema": "jsii/0.10.0", "targets": { "dotnet": { "assemblyOriginatorKeyFile": "../../key.snk", "iconUrl": "https://raw.githubusercontent.com/aws/aws-cdk/master/logo/default-256-dark.png", "namespace": "Amazon.CDK.RegionInfo", "packageId": "Amazon.CDK.RegionInfo", "signAssembly": true }, "java": { "maven": { "artifactId": "cdk-region-info", "groupId": "software.amazon.awscdk" }, "package": "software.amazon.awscdk.regioninfo" }, "js": { "npm": "@aws-cdk/region-info" }, "python": { "distName": "aws-cdk.region-info", "module": "aws_cdk.region_info" } }, "types": { "@aws-cdk/region-info.Default": { "assembly": "@aws-cdk/region-info", "docs": { "stability": "experimental", "summary": "Provides default values for certain regional information points." }, "fqn": "@aws-cdk/region-info.Default", "kind": "class", "locationInModule": { "filename": "lib/default.ts", "line": 4 }, "methods": [ { "docs": { "remarks": "This is useful for example when\nyou need to compute a service principal name, but you do not have a synthesize-time region literal available (so\nall you have is `{ \"Ref\": \"AWS::Region\" }`). This way you get the same defaulting behavior that is normally used\nfor built-in data.", "stability": "experimental", "summary": "Computes a \"standard\" AWS Service principal for a given service, region and suffix." }, "locationInModule": { "filename": "lib/default.ts", "line": 23 }, "name": "servicePrincipal", "parameters": [ { "docs": { "summary": "the name of the service (s3, s3.amazonaws.com, ...)." }, "name": "service", "type": { "primitive": "string" } }, { "docs": { "summary": "the region in which the service principal is needed." }, "name": "region", "type": { "primitive": "string" } }, { "docs": { "summary": "the URL suffix for the partition in which the region is located." }, "name": "urlSuffix", "type": { "primitive": "string" } } ], "returns": { "type": { "primitive": "string" } }, "static": true } ], "name": "Default", "properties": [ { "const": true, "docs": { "stability": "experimental", "summary": "The default value for a VPC Endpoint Service name prefix, useful if you do not have a synthesize-time region literal available (all you have is `{ \"Ref\": \"AWS::Region\" }`)." }, "immutable": true, "locationInModule": { "filename": "lib/default.ts", "line": 11 }, "name": "VPC_ENDPOINT_SERVICE_NAME_PREFIX", "static": true, "type": { "primitive": "string" } } ] }, "@aws-cdk/region-info.Fact": { "assembly": "@aws-cdk/region-info", "docs": { "stability": "experimental", "summary": "A database of regional information." }, "fqn": "@aws-cdk/region-info.Fact", "kind": "class", "locationInModule": { "filename": "lib/fact.ts", "line": 4 }, "methods": [ { "docs": { "returns": "the fact value if it is known, and `undefined` otherwise.", "stability": "experimental", "summary": "Retrieves a fact from this Fact database." }, "locationInModule": { "filename": "lib/fact.ts", "line": 21 }, "name": "find", "parameters": [ { "docs": { "summary": "the name of the region (e.g: `us-east-1`)." }, "name": "region", "type": { "primitive": "string" } }, { "docs": { "summary": "the name of the fact being looked up (see the `FactName` class for details)." }, "name": "name", "type": { "primitive": "string" } } ], "returns": { "optional": true, "type": { "primitive": "string" } }, "static": true }, { "docs": { "stability": "experimental", "summary": "Registers a new fact in this Fact database." }, "locationInModule": { "filename": "lib/fact.ts", "line": 49 }, "name": "register", "parameters": [ { "docs": { "summary": "the new fact to be registered." }, "name": "fact", "type": { "fqn": "@aws-cdk/region-info.IFact" } }, { "docs": { "summary": "whether new facts can replace existing facts or not." }, "name": "allowReplacing", "optional": true, "type": { "primitive": "boolean" } } ], "static": true }, { "docs": { "remarks": "(retrieval will fail if the specified region or\nfact name does not exist.)", "stability": "experimental", "summary": "Retrieve a fact from the Fact database." }, "locationInModule": { "filename": "lib/fact.ts", "line": 33 }, "name": "requireFact", "parameters": [ { "docs": { "summary": "the name of the region (e.g: `us-east-1`)." }, "name": "region", "type": { "primitive": "string" } }, { "docs": { "summary": "the name of the fact being looked up (see the `FactName` class for details)." }, "name": "name", "type": { "primitive": "string" } } ], "returns": { "type": { "primitive": "string" } }, "static": true }, { "docs": { "stability": "experimental", "summary": "Removes a fact from the database." }, "locationInModule": { "filename": "lib/fact.ts", "line": 66 }, "name": "unregister", "parameters": [ { "docs": { "summary": "the region for which the fact is to be removed." }, "name": "region", "type": { "primitive": "string" } }, { "docs": { "summary": "the name of the fact to remove." }, "name": "name", "type": { "primitive": "string" } }, { "docs": { "summary": "the value that should be removed (removal will fail if the value is specified, but does not match the current stored value)." }, "name": "value", "optional": true, "type": { "primitive": "string" } } ], "static": true } ], "name": "Fact", "properties": [ { "docs": { "returns": "the list of names of AWS regions for which there is at least one registered fact. This\nmay not be an exhaustive list of all available AWS regions.", "stability": "experimental" }, "immutable": true, "locationInModule": { "filename": "lib/fact.ts", "line": 9 }, "name": "regions", "static": true, "type": { "collection": { "elementtype": { "primitive": "string" }, "kind": "array" } } } ] }, "@aws-cdk/region-info.FactName": { "assembly": "@aws-cdk/region-info", "docs": { "stability": "experimental", "summary": "All standardized fact names." }, "fqn": "@aws-cdk/region-info.FactName", "initializer": { "docs": { "stability": "experimental" } }, "kind": "class", "locationInModule": { "filename": "lib/fact.ts", "line": 104 }, "methods": [ { "docs": { "stability": "experimental", "summary": "The name of the regional service principal for a given service." }, "locationInModule": { "filename": "lib/fact.ts", "line": 156 }, "name": "servicePrincipal", "parameters": [ { "docs": { "summary": "the service name, either simple (e.g: `s3`, `codedeploy`) or qualified (e.g: `s3.amazonaws.com`). The `.amazonaws.com` and `.amazonaws.com.cn` domains are stripped from service names, so they are canonicalized in that respect." }, "name": "service", "type": { "primitive": "string" } } ], "returns": { "type": { "primitive": "string" } }, "static": true } ], "name": "FactName", "properties": [ { "const": true, "docs": { "remarks": "The value is a boolean\nmodelled as `YES` or `NO`.", "stability": "experimental", "summary": "Whether the AWS::CDK::Metadata CloudFormation Resource is available in-region or not." }, "immutable": true, "locationInModule": { "filename": "lib/fact.ts", "line": 119 }, "name": "CDK_METADATA_RESOURCE_AVAILABLE", "static": true, "type": { "primitive": "string" } }, { "const": true, "docs": { "stability": "experimental", "summary": "The ID of the AWS account that owns the public ECR repository that contains the AWS Deep Learning Containers images in a given region." }, "immutable": true, "locationInModule": { "filename": "lib/fact.ts", "line": 147 }, "name": "DLC_REPOSITORY_ACCOUNT", "static": true, "type": { "primitive": "string" } }, { "const": true, "docs": { "stability": "experimental", "summary": "The domain suffix for a region (e.g: 'amazonaws.com`)." }, "immutable": true, "locationInModule": { "filename": "lib/fact.ts", "line": 113 }, "name": "DOMAIN_SUFFIX", "static": true, "type": { "primitive": "string" } }, { "const": true, "docs": { "stability": "experimental", "summary": "The account for ELBv2 in this region." }, "immutable": true, "locationInModule": { "filename": "lib/fact.ts", "line": 141 }, "name": "ELBV2_ACCOUNT", "static": true, "type": { "primitive": "string" } }, { "const": true, "docs": { "stability": "experimental", "summary": "The name of the partition for a region (e.g: 'aws', 'aws-cn', ...)." }, "immutable": true, "locationInModule": { "filename": "lib/fact.ts", "line": 108 }, "name": "PARTITION", "static": true, "type": { "primitive": "string" } }, { "const": true, "docs": { "stability": "experimental", "summary": "The endpoint used for hosting S3 static websites." }, "immutable": true, "locationInModule": { "filename": "lib/fact.ts", "line": 124 }, "name": "S3_STATIC_WEBSITE_ENDPOINT", "static": true, "type": { "primitive": "string" } }, { "const": true, "docs": { "stability": "experimental", "summary": "The endpoint used for aliasing S3 static websites in Route 53." }, "immutable": true, "locationInModule": { "filename": "lib/fact.ts", "line": 129 }, "name": "S3_STATIC_WEBSITE_ZONE_53_HOSTED_ZONE_ID", "static": true, "type": { "primitive": "string" } }, { "const": true, "docs": { "stability": "experimental", "summary": "The prefix for VPC Endpoint Service names, cn.com.amazonaws.vpce for China regions, com.amazonaws.vpce otherwise." }, "immutable": true, "locationInModule": { "filename": "lib/fact.ts", "line": 136 }, "name": "VPC_ENDPOINT_SERVICE_NAME_PREFIX", "static": true, "type": { "primitive": "string" } } ] }, "@aws-cdk/region-info.IFact": { "assembly": "@aws-cdk/region-info", "docs": { "stability": "experimental", "summary": "A fact that can be registered about a particular region." }, "fqn": "@aws-cdk/region-info.IFact", "kind": "interface", "locationInModule": { "filename": "lib/fact.ts", "line": 84 }, "name": "IFact", "properties": [ { "abstract": true, "docs": { "remarks": "Standardized values are provided by the `Facts` class.", "stability": "experimental", "summary": "The name of this fact." }, "immutable": true, "locationInModule": { "filename": "lib/fact.ts", "line": 93 }, "name": "name", "type": { "primitive": "string" } }, { "abstract": true, "docs": { "stability": "experimental", "summary": "The region for which this fact applies." }, "immutable": true, "locationInModule": { "filename": "lib/fact.ts", "line": 88 }, "name": "region", "type": { "primitive": "string" } }, { "abstract": true, "docs": { "stability": "experimental", "summary": "The value of this fact." }, "immutable": true, "locationInModule": { "filename": "lib/fact.ts", "line": 98 }, "name": "value", "optional": true, "type": { "primitive": "string" } } ] }, "@aws-cdk/region-info.RegionInfo": { "assembly": "@aws-cdk/region-info", "docs": { "stability": "experimental", "summary": "Information pertaining to an AWS region." }, "fqn": "@aws-cdk/region-info.RegionInfo", "kind": "class", "locationInModule": { "filename": "lib/region-info.ts", "line": 6 }, "methods": [ { "docs": { "stability": "experimental", "summary": "Obtain region info for a given region name." }, "locationInModule": { "filename": "lib/region-info.ts", "line": 39 }, "name": "get", "parameters": [ { "docs": { "summary": "the name of the region (e.g: us-east-1)." }, "name": "name", "type": { "primitive": "string" } } ], "returns": { "type": { "fqn": "@aws-cdk/region-info.RegionInfo" } }, "static": true }, { "docs": { "returns": "a mapping with AWS region codes as the keys,\nand the fact in the given region as the value for that key", "stability": "experimental", "summary": "Retrieves a collection of all fact values for all regions that fact is defined in." }, "locationInModule": { "filename": "lib/region-info.ts", "line": 23 }, "name": "regionMap", "parameters": [ { "docs": { "remarks": "For a list of common fact names, see the FactName class", "summary": "the name of the fact to retrieve values for." }, "name": "factName", "type": { "primitive": "string" } } ], "returns": { "type": { "collection": { "elementtype": { "primitive": "string" }, "kind": "map" } } }, "static": true }, { "docs": { "stability": "experimental", "summary": "The name of the service principal for a given service in this region." }, "locationInModule": { "filename": "lib/region-info.ts", "line": 93 }, "name": "servicePrincipal", "parameters": [ { "docs": { "summary": "the service name (e.g: s3.amazonaws.com)." }, "name": "service", "type": { "primitive": "string" } } ], "returns": { "optional": true, "type": { "primitive": "string" } } } ], "name": "RegionInfo", "properties": [ { "docs": { "returns": "the list of names of AWS regions for which there is at least one registered fact. This\nmay not be an exaustive list of all available AWS regions.", "stability": "experimental" }, "immutable": true, "locationInModule": { "filename": "lib/region-info.ts", "line": 11 }, "name": "regions", "static": true, "type": { "collection": { "elementtype": { "fqn": "@aws-cdk/region-info.RegionInfo" }, "kind": "array" } } }, { "docs": { "stability": "experimental", "summary": "Whether the `AWS::CDK::Metadata` CloudFormation Resource is available in this region or not." }, "immutable": true, "locationInModule": { "filename": "lib/region-info.ts", "line": 48 }, "name": "cdkMetadataResourceAvailable", "type": { "primitive": "boolean" } }, { "docs": { "stability": "experimental" }, "immutable": true, "locationInModule": { "filename": "lib/region-info.ts", "line": 43 }, "name": "name", "type": { "primitive": "string" } }, { "docs": { "stability": "experimental", "summary": "The ID of the AWS account that owns the public ECR repository containing the AWS Deep Learning Containers images in this region." }, "immutable": true, "locationInModule": { "filename": "lib/region-info.ts", "line": 109 }, "name": "dlcRepositoryAccount", "optional": true, "type": { "primitive": "string" } }, { "docs": { "stability": "experimental", "summary": "The domain name suffix (e.g: amazonaws.com) for this region." }, "immutable": true, "locationInModule": { "filename": "lib/region-info.ts", "line": 55 }, "name": "domainSuffix", "optional": true, "type": { "primitive": "string" } }, { "docs": { "stability": "experimental", "summary": "The account ID for ELBv2 in this region." }, "immutable": true, "locationInModule": { "filename": "lib/region-info.ts", "line": 101 }, "name": "elbv2Account", "optional": true, "type": { "primitive": "string" } }, { "docs": { "stability": "experimental", "summary": "The name of the ARN partition for this region (e.g: aws)." }, "immutable": true, "locationInModule": { "filename": "lib/region-info.ts", "line": 62 }, "name": "partition", "optional": true, "type": { "primitive": "string" } }, { "docs": { "stability": "experimental", "summary": "The endpoint used by S3 static website hosting in this region (e.g: s3-static-website-us-east-1.amazonaws.com)." }, "immutable": true, "locationInModule": { "filename": "lib/region-info.ts", "line": 69 }, "name": "s3StaticWebsiteEndpoint", "optional": true, "type": { "primitive": "string" } }, { "docs": { "stability": "experimental", "summary": "The hosted zone ID used by Route 53 to alias a S3 static website in this region (e.g: Z2O1EMRO9K5GLX)." }, "immutable": true, "locationInModule": { "filename": "lib/region-info.ts", "line": 76 }, "name": "s3StaticWebsiteHostedZoneId", "optional": true, "type": { "primitive": "string" } }, { "docs": { "stability": "experimental", "summary": "The prefix for VPC Endpoint Service names, cn.com.amazonaws.vpce for China regions, com.amazonaws.vpce otherwise." }, "immutable": true, "locationInModule": { "filename": "lib/region-info.ts", "line": 85 }, "name": "vpcEndpointServiceNamePrefix", "optional": true, "type": { "primitive": "string" } } ] } }, "version": "1.64.0", "fingerprint": "Ns4+4fDUtUCzbNmIsh/GnGxSpr0IO6MffIhE5O0hobU=" }