From 54ca9105194767c6d8401c7f439ff7919c225b4a Mon Sep 17 00:00:00 2001 From: Julian Michel Date: Fri, 22 Oct 2021 06:01:34 +0200 Subject: [PATCH] docs(core): fix CfnMapping example (#16882) The CloudFormation intrinsic function `Fn::FindInMap` only supports alphanumeric characters as name. However, the `CfnMapping` examples in the README file contain hyphens in the name field. This causes an error when the code is deployed. I changed the structure of the examples to create examples that can be deployed in AWS. Fixes #16866. ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license* --- packages/@aws-cdk/core/README.md | 35 ++++++++++++++++++-------------- packages/aws-cdk-lib/README.md | 35 ++++++++++++++++++-------------- 2 files changed, 40 insertions(+), 30 deletions(-) diff --git a/packages/@aws-cdk/core/README.md b/packages/@aws-cdk/core/README.md index a6d4d2efc5a9b..1090d893c508d 100644 --- a/packages/@aws-cdk/core/README.md +++ b/packages/@aws-cdk/core/README.md @@ -753,16 +753,19 @@ CloudFormation [mappings][cfn-mappings] are created and queried using the ```ts const regionTable = new CfnMapping(this, 'RegionTable', { mapping: { - regionName: { - 'us-east-1': 'US East (N. Virginia)', - 'us-east-2': 'US East (Ohio)', + 'us-east-1': { + regionName: 'US East (N. Virginia)', + // ... + }, + 'us-east-2': { + regionName: 'US East (Ohio)', // ... }, // ... } }); -regionTable.findInMap('regionName', Aws.REGION); +regionTable.findInMap(Aws.REGION, 'regionName') ``` This will yield the following template: @@ -770,9 +773,10 @@ This will yield the following template: ```yaml Mappings: RegionTable: - regionName: - us-east-1: US East (N. Virginia) - us-east-2: US East (Ohio) + us-east-1: + regionName: US East (N. Virginia) + us-east-2: + regionName: US East (Ohio) ``` Mappings can also be synthesized "lazily"; lazy mappings will only render a "Mappings" @@ -787,24 +791,25 @@ call to `findInMap` will be able to resolve the value during synthesis and simpl ```ts const regionTable = new CfnMapping(this, 'RegionTable', { mapping: { - regionName: { - 'us-east-1': 'US East (N. Virginia)', - 'us-east-2': 'US East (Ohio)', + 'us-east-1': { + regionName: 'US East (N. Virginia)', + }, + 'us-east-2': { + regionName: 'US East (Ohio)', }, }, lazy: true, }); -regionTable.findInMap('regionName', 'us-east-2'); +regionTable.findInMap('us-east-2', 'regionName'); ``` On the other hand, the following code will produce the "Mappings" section shown above, -since the second-level key is an unresolved token. The call to `findInMap` will return a -token that resolves to `{ Fn::FindInMap: [ 'RegionTable', 'regionName', { Ref: AWS::Region -} ] }`. +since the top-level key is an unresolved token. The call to `findInMap` will return a token that resolves to +`{ "Fn::FindInMap": [ "RegionTable", { "Ref": "AWS::Region" }, "regionName" ] }`. ```ts -regionTable.findInMap('regionName', Aws.REGION); +regionTable.findInMap(Aws.REGION, 'regionName'); ``` [cfn-mappings]: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/mappings-section-structure.html diff --git a/packages/aws-cdk-lib/README.md b/packages/aws-cdk-lib/README.md index 48d4cd65f93a5..5d225ce542aa5 100644 --- a/packages/aws-cdk-lib/README.md +++ b/packages/aws-cdk-lib/README.md @@ -786,16 +786,19 @@ CloudFormation [mappings][cfn-mappings] are created and queried using the ```ts const regionTable = new CfnMapping(this, 'RegionTable', { mapping: { - regionName: { - 'us-east-1': 'US East (N. Virginia)', - 'us-east-2': 'US East (Ohio)', + 'us-east-1': { + regionName: 'US East (N. Virginia)', + // ... + }, + 'us-east-2': { + regionName: 'US East (Ohio)', // ... }, // ... } }); -regionTable.findInMap('regionName', Aws.REGION); +regionTable.findInMap(Aws.REGION, 'regionName') ``` This will yield the following template: @@ -803,9 +806,10 @@ This will yield the following template: ```yaml Mappings: RegionTable: - regionName: - us-east-1: US East (N. Virginia) - us-east-2: US East (Ohio) + us-east-1: + regionName: US East (N. Virginia) + us-east-2: + regionName: US East (Ohio) ``` Mappings can also be synthesized "lazily"; lazy mappings will only render a "Mappings" @@ -820,24 +824,25 @@ call to `findInMap` will be able to resolve the value during synthesis and simpl ```ts const regionTable = new CfnMapping(this, 'RegionTable', { mapping: { - regionName: { - 'us-east-1': 'US East (N. Virginia)', - 'us-east-2': 'US East (Ohio)', + 'us-east-1': { + regionName: 'US East (N. Virginia)', + }, + 'us-east-2': { + regionName: 'US East (Ohio)', }, }, lazy: true, }); -regionTable.findInMap('regionName', 'us-east-2'); +regionTable.findInMap('us-east-2', 'regionName'); ``` On the other hand, the following code will produce the "Mappings" section shown above, -since the second-level key is an unresolved token. The call to `findInMap` will return a -token that resolves to `{ Fn::FindInMap: [ 'RegionTable', 'regionName', { Ref: AWS::Region -} ] }`. +since the top-level key is an unresolved token. The call to `findInMap` will return a token that resolves to +`{ "Fn::FindInMap": [ "RegionTable", { "Ref": "AWS::Region" }, "regionName" ] }`. ```ts -regionTable.findInMap('regionName', Aws.REGION); +regionTable.findInMap(Aws.REGION, 'regionName'); ``` [cfn-mappings]: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/mappings-section-structure.html