From f69787667d683f01f7a372038e40b372d5621700 Mon Sep 17 00:00:00 2001 From: Doug Date: Wed, 26 Sep 2018 01:10:40 -0700 Subject: [PATCH] docs: Add info about passing values into a stack (#700) Explain the options users have for passing information into CDK apps. --- docs/src/concepts.rst | 1 + docs/src/passing-in-data.rst | 219 +++++++++++++++++++++++++++++++++++ 2 files changed, 220 insertions(+) create mode 100644 docs/src/passing-in-data.rst diff --git a/docs/src/concepts.rst b/docs/src/concepts.rst index 8987ada23fced..dd1e2aa81d3c1 100644 --- a/docs/src/concepts.rst +++ b/docs/src/concepts.rst @@ -43,6 +43,7 @@ as shared class libraries. logical-ids environments apps + passing-in-data context assets applets diff --git a/docs/src/passing-in-data.rst b/docs/src/passing-in-data.rst new file mode 100644 index 0000000000000..cde1fec8e302f --- /dev/null +++ b/docs/src/passing-in-data.rst @@ -0,0 +1,219 @@ +.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. + + This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 + International License (the "License"). You may not use this file except in compliance with the + License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. + + This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + either express or implied. See the License for the specific language governing permissions and + limitations under the License. + +.. _passing_in_values: + +############################################ +Passing in External Values to Your |cdk| App +############################################ + +.. See https://github.com/awslabs/aws-cdk/issues/603 (includes work from the following PR) + https://github.com/awslabs/aws-cdk/pull/183 + +There may be cases where you want to parameterize one or more of your stack resources. +Therefore, you want to be able to pass values into your app from outside your app. +Currently, you can get values into your app from outside your app through any of the following. + +- Using a context variable +- Using an environment variable +- Using an SSM Parameter Store variable +- Using a value from another stack +- Using a |CFN| parameter +- Using a resource in an existing |CFN| template + +Each of these techniques is described in the following sections. + +.. _passing_in_values_from_context: + +Getting a Value from a Context Variable +======================================= + +You can specify a context variable either as +part of a |toolkit| command, +or in a **context** section of *cdk.json*. + +To create a command-line context variable, +use the **--context** (**-c**) option of a |toolkit| command, +as shown in the following example. + +.. code-block:: sh + + cdk synth -c bucket_name=mygroovybucket + +To specify the same context variable and value in *cdk.json*: + +.. code-block:: json + + { + "context": { + "bucket_name": "myotherbucket" + } + } + +To get the value of a context variable in your app, +use code like the following, +which gets the value of the context variable **bucket_name**. + +.. code-block:: ts + + const bucket_name string = this.getContext("bucket_name"); + +.. _passing_in_value_from_env_vars: + +Getting a Value from an Environment Variable +============================================ + +To get the value of an environment variable, +use code like the following, +which gets the value of the environment variable **MYBUCKET**. + +.. code-block:: ts + + const bucket_name = process.env.MYBUCKET; + +.. _passing_in_value_from_ssm: + +Getting a Value from an SSM Store Variable +========================================== + +To get the value of an SSM parameter store variable, +use code like the following, +which uses the value of the SSM variable **my-awesome-value**. + +.. code-block:: ts + + const myvalue = new SSMParameterProvider(this).getString("my-awesome-value"); + +See the :doc:`context` topic for information about the :py:class:`SSMParameterProvider <@aws-cdk/cdk.SSMParameterProvider>`. + +.. _passing_in_value_between_stacks: + +Passing in a Value From Another Stack +===================================== + +You can pass a value from one stack to another stack in the same app +by using the **export** method in one stack and the **import** method in the other stack. + +The following example creates a bucket on one stack +and passes a reference to that bucket to the other stack through an interface. + +First create a stack with a bucket. +The stack includes a a property we use to pass the bucket's properties to the other stack. +Note how we use the **export** method on the bucket to get it's properties and save them +in the stack property. + +.. code-block:: ts + + class HelloCdkStack extends cdk.Stack { + // Property that defines the stack you are exporting from + public readonly myBucketRefProps: s3.BucketRefProps; + + constructor(parent: cdk.App, name: string, props?: cdk.StackProps) { + super(parent, name, props); + + const mybucket = new s3.Bucket(this, "MyFirstBucket"); + + // Save bucket's *BucketRefProps* + this.myBucketRefProps = mybucket.export(); + } + } + +Create an interface for the second stack's properties. +We use this interface to pass the bucket properties between the two stacks. + +.. code-block:: ts + + // Interface we'll use to pass the bucket's properties to another stack + interface MyCdkStackProps { + theBucketRefProps: s3.BucketRefProps; + } + +Create the second stack that gets a reference to the other bucket +from the properties passed in through the constructor. + +.. code-block:: ts + + // The class for the other stack + class MyCdkStack extends cdk.Stack { + constructor(parent: cdk.App, name: string, props: MyCdkStackProps) { + super(parent, name); + + const myOtherBucket = s3.Bucket.import(this, "MyOtherBucket", props.theBucketRefProps); + + // Do something with myOtherBucket + } + } + +Finally, connect the dots in your app. + +.. code-block:: ts + + const app = new cdk.App(process.argv); + + const myStack = new HelloCdkStack(app, "HelloCdkStack"); + + new MyCdkStack(app, "MyCdkStack", { + theBucketRefProps: myStack.myBucketRefProps + }); + + process.stdout.write(app.run()); + +.. _using_cfn_parameter: + +Using an |CFN| Parameter +======================== + +See the +`Parameters `_ +topic for information about using the optional *Parameters* section to customize your |CFN| templates. + +You can also get a reference to a resource in an existing |CFN| template, +as described in :doc:`concepts`. + +.. _using_cfn_template: + +Using an Existing |CFN| Template +================================ + +The |cdk| provides a mechanism that you can use to +incorporate resources from an existing |CFN| template +into your |cdk| app. +For example, suppose you have a template, +*my-template.json*, +with the following resource, +where **S3Bucket** is the logical ID of the bucket in your template: + +.. code-block:: json + + "S3Bucket": { + "Type": "AWS::S3::Bucket", + "Properties": { + ... + } + } + +You can include this bucket in your |cdk| app, +as shown in the following example +(note that you cannot use this method in an |l2| construct): + +.. code-block:: ts + + import cdk = require("@aws-cdk/cdk"); + import fs = require("fs"); + + new cdk.Include(this, "ExistingInfrastructure", { + template: JSON.parse(fs.readFileSync("my-template.json").toString()) + }); + +Then to access an attribute of the resource, such as the bucket's ARN: + +.. code-block:: ts + + const bucketArn = new cdk.FnGetAtt("S3Bucket", "Arn");