From 503d2f75ffcbc89ac3861ea88ad6fe316085f274 Mon Sep 17 00:00:00 2001 From: Elad Ben-Israel Date: Fri, 29 Jun 2018 19:12:38 -0700 Subject: [PATCH] Improvements to Logical IDs topic Bring up `renameLogical` earlier and clean up some phrasing --- packages/aws-cdk-docs/src/logical-ids.rst | 57 ++++++++++++++--------- 1 file changed, 35 insertions(+), 22 deletions(-) diff --git a/packages/aws-cdk-docs/src/logical-ids.rst b/packages/aws-cdk-docs/src/logical-ids.rst index 6677ff15e72be..d9b93c5242356 100644 --- a/packages/aws-cdk-docs/src/logical-ids.rst +++ b/packages/aws-cdk-docs/src/logical-ids.rst @@ -14,7 +14,7 @@ Logical IDs ########### -When you synthesize a stack into a |CFN| template, +When you synthesize a stack into an |CFN| template, the |cdk| assigns a `logical ID `_, which must be unique within the template, @@ -29,25 +29,25 @@ to each resource in the stack. updates the stack. Each resource in the construct tree has a unique path that represents its -location within the tree. The logical ID of a resource is formed by -concatenating the names of all of the constructs in the resource's path, and -appending an eight-character MD5 hash of the path. This final component is -necessary since |CFN| logical IDs cannot include the delimiting slash -character (/), so simply concatenating the component values does not work. For -example, concatenating the components of the path */a/b/c* produces **abc**, -which is the same as concatenating the components of the path */ab/c*. - +location within the tree. Since logical IDs can only use alphanumeric characters and also restricted in -length, we are unable to simply use a delimited path as the logical ID. Instead -IDs are allocated by concatenating a human-friendly rendition from the path -(concatenation, de-duplicate, trim) with a short MD5 hash of the delimited path: +length, we are unable to simply use a delimited path as the logical ID. +Instead, logical IDs are allocated by concatenating a human-friendly rendition +from the path (concatenation, de-duplicate, trim) with an eight-character MD5 +hash of the delimited path. +This final component is necessary since |CFN| logical IDs cannot include +the delimiting slash character (/), so simply concatenating the component +values does not work. For example, concatenating the components of the +path */a/b/c* produces **abc**, which is the same as concatenating the components of +the path */ab/c*. .. code-block:: text VPCPrivateSubnet2RouteTable0A19E10E <-----------human---------><-hash-> -Resources that are direct children of the |stack-class| class use +Low-level CloudFormation resources (from `@aws-cdk/resources`) +that are direct children of the |stack-class| class use their name as their logical ID without modification. This makes it easier to port existing templates into a CDK app. @@ -65,10 +65,6 @@ Logical IDs are unique within the stack Logical IDs remain unchanged across updates This is true as long as their location within the construct tree doesn't change. -.. See :ref:`creating_runtime_value` - for information on how to retain - logical IDs despite structural changes in your stack. - The |cdk| applies some heuristics to improve the human-friendliness of the prefix: - If a path component is **Resource**, it is omitted. @@ -80,9 +76,28 @@ The |cdk| applies some heuristics to improve the human-friendliness of the prefi .. _changing_logical_ids: -Changing Logical IDs +Renaming Logical IDs ==================== +The :py:meth:`aws-cdk.Stack.renameLogical` method can be used to explicitly assign +logical IDs to certain resources, given either their full path or + +.. code-block:: javascript + + class MyStack extends Stack { + constructor(parent: App, name: string, props: StackProps) { + super(parent, name); + + // note that `renameLogical` must be called /before/ defining the construct. + // a good practice would be to always put these at the top of your stack initializer. + this.renameLogical('MyTableCD117FA1', 'MyTable'); + this.renameLogical('MyQueueAB4432A3', 'MyAwesomeQueue'); + + new Table(this, 'MyTable'); + new Queue(this, 'MyQueue'); + } + } + In some cases changing a resource results in a structural change, which results in a different path, @@ -113,7 +128,5 @@ stacks. `cdk diff` will tell you which resources are about to be destroyed: [-] ☢️ Destroying MyTable (type: AWS::DynamoDB::Table) [+] 🆕 Creating MyTableCD117FA1 (type: AWS::DynamoDB::Table) -- :py:meth:`aws-cdk.Stack.renameLogical` where :code:`from` is either an explicit logical ID or a path. - Call this method after the resource has been added to the stack. -- :py:attr:`aws-cdk.Resource.logicalId` allows assigning a fixed logical ID to a resource, - and opt-out from using the scheme described above. +Now, you can add a :py:meth:`aws-cdk.Stack.renameLogical` call before the +table is defined to rename **MyTableCD117FA1** to **MyTable**.