1  # AWS Region-Specific Information Directory
 2  <!--BEGIN STABILITY BANNER-->
 3  
 4  ---
 5  
 6  ![cdk-constructs: Stable](https://img.shields.io/badge/cdk--constructs-stable-success.svg?style=for-the-badge)
 7  
 8  ---
 9  
10  <!--END STABILITY BANNER-->
11  
12  ## Usage
13  
14  Some information used in CDK Applications differs from one AWS region to
15  another, such as service principals used in IAM policies, S3 static website
16  endpoints, ...
17  
18  ### The `RegionInfo` class
19  
20  The library offers a simple interface to obtain region specific information in
21  the form of the `RegionInfo` class. This is the preferred way to interact with
22  the regional information database:
23  
24  ```ts
25  import { RegionInfo } from '@aws-cdk/region-info';
26  
27  // Get the information for "eu-west-1":
28  const region = RegionInfo.get('eu-west-1');
29  
30  // Access attributes:
31  region.s3StaticWebsiteEndpoint; // s3-website-eu-west-1.amazonaws.com
32  region.servicePrincipal('logs.amazonaws.com'); // logs.eu-west-1.amazonaws.com
33  ```
34  
35  The `RegionInfo` layer is built on top of the Low-Level API, which is described
36  below and can be used to register additional data, including user-defined facts
37  that are not available through the `RegionInfo` interface.
38  
39  ### Low-Level API
40  
41  This library offers a primitive database of such information so that CDK
42  constructs can easily access regional information. The `FactName` class provides
43  a list of known fact names, which can then be used with the `RegionInfo` to
44  retrieve a particular value:
45  
46  ```ts
47  import * as regionInfo from '@aws-cdk/region-info';
48  
49  const codeDeployPrincipal = regionInfo.Fact.find('us-east-1', regionInfo.FactName.servicePrincipal('codedeploy.amazonaws.com'));
50  // => codedeploy.us-east-1.amazonaws.com
51  
52  const staticWebsite = regionInfo.Fact.find('ap-northeast-1', regionInfo.FactName.S3_STATIC_WEBSITE_ENDPOINT);
53  // => s3-website-ap-northeast-1.amazonaws.com
54  ```
55  
56  ## Supplying new or missing information
57  
58  As new regions are released, it might happen that a particular fact you need is
59  missing from the library. In such cases, the `Fact.register` method can be used
60  to inject FactName into the database:
61  
62  ```ts
63  regionInfo.Fact.register({
64    region: 'bermuda-triangle-1',
65    name: regionInfo.FactName.servicePrincipal('s3.amazonaws.com'),
66    value: 's3-website.bermuda-triangle-1.nowhere.com',
67  });
68  ```
69  
70  ## Overriding incorrect information
71  
72  In the event information provided by the library is incorrect, it can be
73  overridden using the same `Fact.register` method demonstrated above, simply
74  adding an extra boolean argument:
75  
76  ```ts
77  regionInfo.Fact.register({
78    region: 'us-east-1',
79    name: regionInfo.FactName.servicePrincipal('service.amazonaws.com'),
80    value: 'the-correct-principal.amazonaws.com',
81  }, true /* Allow overriding information */);
82  ```
83  
84  If you happen to have stumbled upon incorrect data built into this library, it
85  is always a good idea to report your findings in a [GitHub issue], so we can fix
86  it for everyone else!
87  
88  [GitHub issue]: https://github.com/aws/aws-cdk/issues
89  
90  ---
91  
92  This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) project.