From 4afacedec1f613b7f28c2ccc4a6fc3afc069582c Mon Sep 17 00:00:00 2001 From: Elad Ben-Israel Date: Wed, 1 Aug 2018 10:45:24 +0300 Subject: [PATCH] Doc improvements (#462) * Explain about AWS::CDK::Metadata * Explain about logical IDS versus physical names and add link * Add "What Next?" section in the end with suggested next steps * Other minor fixes. Reference: * Changed sidebar title from "Module Reference" to "Reference" * Reduced TOC depth to 1 Misc: * Changed Gitter URL * Extract a `context` topic from `environments`. * Refactored the versioning reporting section. Fixes #451 --- packages/@aws-cdk/cdk/README.md | 7 +- packages/@aws-cdk/cdk/package.json | 2 +- packages/aws-cdk-docs/src/concepts.rst | 1 + packages/aws-cdk-docs/src/context.rst | 44 +++++++++++ packages/aws-cdk-docs/src/environments.rst | 32 -------- packages/aws-cdk-docs/src/getting-started.rst | 76 +++++++++++++------ packages/aws-cdk-docs/src/index.rst | 4 +- .../aws-cdk-docs/src/reference.rst.template | 2 +- packages/aws-cdk-docs/src/tools.rst | 30 ++++++-- 9 files changed, 132 insertions(+), 66 deletions(-) create mode 100644 packages/aws-cdk-docs/src/context.rst diff --git a/packages/@aws-cdk/cdk/README.md b/packages/@aws-cdk/cdk/README.md index 8460ea17805c0..f1dcb5bfd938c 100644 --- a/packages/@aws-cdk/cdk/README.md +++ b/packages/@aws-cdk/cdk/README.md @@ -1,2 +1,5 @@ -## AWS Cloud Development Kit for Javascript -This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project. \ No newline at end of file +## AWS Cloud Development Kit Core Library + +This library includes the basic building blocks of +the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) (AWS CDK). + diff --git a/packages/@aws-cdk/cdk/package.json b/packages/@aws-cdk/cdk/package.json index 34b0d52ccb02c..fe565b5aee9dd 100644 --- a/packages/@aws-cdk/cdk/package.json +++ b/packages/@aws-cdk/cdk/package.json @@ -1,7 +1,7 @@ { "name": "@aws-cdk/cdk", "version": "0.8.0", - "description": "AWS Cloud Development Kit for Javascript", + "description": "AWS Cloud Development Kit Core Library", "main": "lib/index.js", "types": "lib/index.d.ts", "jsii": { diff --git a/packages/aws-cdk-docs/src/concepts.rst b/packages/aws-cdk-docs/src/concepts.rst index 932cc81e672fc..6f6e9bd58d247 100644 --- a/packages/aws-cdk-docs/src/concepts.rst +++ b/packages/aws-cdk-docs/src/concepts.rst @@ -43,5 +43,6 @@ as shared class libraries. logical-ids environments apps + context assets applets diff --git a/packages/aws-cdk-docs/src/context.rst b/packages/aws-cdk-docs/src/context.rst new file mode 100644 index 0000000000000..1ea6441a77dca --- /dev/null +++ b/packages/aws-cdk-docs/src/context.rst @@ -0,0 +1,44 @@ +.. 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. + +.. _context: + +##################### +Environmental Context +##################### + +When you synthesize a stack to create a |CFN| template, the |cdk| might need information based on the +environment (account and Region), such as the availability zones or AMIs available in the Region. +To enable this feature, the |toolkit| uses *context providers*, +and saves the context information into |cx-json| +the first time you call |cx-synth-code|. + +The |cdk| currently supports the following context providers. + +:py:class:`AvailabilityZoneProvider <@aws-cdk/cdk.AvailabilityZoneProvider>` + Use this provider to get the list of all supported availability zones in this environment. + For example, the following code iterates over all of the AZs in the current environment. + +.. code:: js + + // "this" refers to a parent Construct + const zones: string[] = new AvailabilityZoneProvider(this).availabilityZones; + + for (let zone of zones) { + // do somethning for each zone! + } + +:py:class:`SSMParameterProvider <@aws-cdk/cdk.SSMParameterProvider>` + Use this provider to read values from the current Region's SSM parameter store. + For example, the follow code returns the value of the 'my-awesome-value' key: + +.. code:: js + + const ami: string = new SSMParameterProvider(this).getString('my-awesome-value'); diff --git a/packages/aws-cdk-docs/src/environments.rst b/packages/aws-cdk-docs/src/environments.rst index 59505708eae45..4506fefde9a6a 100644 --- a/packages/aws-cdk-docs/src/environments.rst +++ b/packages/aws-cdk-docs/src/environments.rst @@ -62,35 +62,3 @@ and explicitly specify accounts and Regions for production stacks. individual accounts so that you can deploy to multiple accounts using one invocation of ``cdk deploy``, but this feature is not available yet. -.. _environment_context: - -Environmental Context -===================== - -When you synthesize a stack to create a |CFN| template, the |cdk| might need information based on the -environment (account and Region), such as the availability zones or AMIs available in the Region. -To enable this feature, the |toolkit| uses *context providers*, -and saves the context information into |cx-json| -the first time you call |cx-synth-code|. - -The |cdk| currently supports the following context providers. - -:py:class:`@aws-cdk/cdk.AvailabilityZoneProvider` - Use this provider to get the list of all supported availability zones in this environment. - For example, the following code iterates over all of the AZs in the current environment. - -.. code:: js - - const zones: string[] = new AvailabilityZoneProvider(this).availabilityZones; - - for (let zone of zones) { - // do somethning for each zone! - } - -:py:class:`@aws-cdk/cdk.SSMParameterProvider` - Use this provider to read values from the current Region's SSM parameter store. - For example, the follow code returns the value of the 'my-awesome-value' key: - -.. code:: js - - const ami: string = new SSMParameterProvider(this).getString('my-awesome-value'); diff --git a/packages/aws-cdk-docs/src/getting-started.rst b/packages/aws-cdk-docs/src/getting-started.rst index b8af73ec9f20f..2f9b81e59a81c 100644 --- a/packages/aws-cdk-docs/src/getting-started.rst +++ b/packages/aws-cdk-docs/src/getting-started.rst @@ -167,9 +167,7 @@ library includes the basic classes needed to write |cdk| stacks and apps. com.amazonaws.cdk aws-cdk - - - |cdk-version| + @@ -342,13 +340,12 @@ your project directory: Specify a **CLASSPATH**, which contains both the compiled code and dependencies, to execute the Java program. - Use **maven-dependency-plugin** to produce the file **.classpath.txt** + + Use **maven-dependency-plugin** in your **pom.xml** file to produce the file **.classpath.txt** whenever the project is compiled: .. code-block:: xml - - @@ -388,7 +385,7 @@ your project directory: #!/bin/bash exec java -cp target/classes:$(cat .classpath.txt) com.acme.MyApp app $@ - Define the :code:`-- app` option in **cdk.json**: + Define the :code:`--app` option in **cdk.json**: .. code-block:: json @@ -523,9 +520,9 @@ together into a tree: * **parent** represents the parent construct. By specifying the parent construct upon initialization, constructs can obtain contextual information when they are initialized. For example, the region a stack is deployed to can be - obtained via a call to **Stack.find(this).requireRegion()**. See Context for - more information. -* **id** is a local string that identifies the construct within the tree. + obtained via a call to :py:meth:`Stack.find(this).requireRegion() <@aws-cdk/cdk.Stack.requireRegion>`. + See :doc:`context` for more information. +* **id** is a string that locally identifies this construct within the tree. Constructs must have a unique ID amongst their siblings. * **props** is the set of initialization properties for this construct. @@ -563,7 +560,8 @@ stack: region: Notice that your stack has been automatically associated with the default AWS -account and region configured in the AWS CLI. +account and region configured in the AWS CLI. See :doc:`environments` for more +details on how to associate stacks to environments. .. _define_bucket: @@ -593,8 +591,15 @@ Install the **@aws-cdk/aws-s3** package: .. group-tab:: Java - During beta, all |cdk| modules are bundles into the **aws-cdk** Maven package, so - there is no need to explicitly install the |S3| library. + Edit your **pom.xml** file: + + .. code-block:: sh + + + com.amazonaws.cdk + aws-s3 + + Next, define an |S3| bucket in the stack. |S3| buckets are represented by the :py:class:`Bucket <@aws-cdk/aws-s3.Bucket>` class: @@ -667,11 +672,18 @@ the :py:class:`Bucket <@aws-cdk/aws-s3.Bucket>` class: A few things to notice: -* **s3.Bucket** is construct. This means it's initialization signature has - **parent**, **id**, and **props**. In this case, the bucket is an immediate - child of **MyStack**, and its ID is 'MyFirstBucket'. -* Since the bucket's :code:`versioned` property is :code:`true`, - versioning is enabled on the bucket. +* :py:class:`Bucket <@aws-cdk/aws-s3.Bucket>` is a construct. + This means it's initialization signature has **parent**, **id**, and **props**. + In this case, the bucket is an immediate child of **MyStack**. +* ``MyFirstBucket`` is the **logical id** of the bucket construct, **not** the physical name of the + S3 bucket. The logical ID is used to uniquely identify resources in your stack + across deployments. See :doc:`logical-ids` for more details on how to work + with logical IDs. To specify a physical name for your bucket, you can set the + :py:meth:`bucketName <@aws-cdk/aws-s3.BucketProps.bucketName>` property when + you define your bucket. +* Since the bucket's :py:meth:`versioned <@aws-cdk/aws-s3.BucketProps.versioned>` + property is :code:`true`, `versioning `_ + is enabled on the bucket. Compile your program: @@ -698,8 +710,7 @@ Compile your program: Synthesize an |CFN| Template ============================ -Synthesize a -|cfn| template for the stack (don't forget to first compile the project if you have made any changes): +Synthesize a |cfn| template for the stack: .. code-block:: sh @@ -718,10 +729,21 @@ This command executes the |cdk| app and synthesize an |CFN| template for the Properties: VersioningConfiguration: Status: Enabled + CDKMetadata: + Type: 'AWS::CDK::Metadata' + Properties: + Modules: # ... You can see that the stack contains an **AWS::S3::Bucket** resource with the desired versioning configuration. +.. note:: + + The **AWS::CDK::Metadata** resource was automatically added to your template + by the toolkit. This allows us to learn which libraries were used in your + stack. See :ref:`version-reporting` for more details and how to + :ref:`opt-out `. + .. _deploy_stack: Deploying the Stack @@ -731,7 +753,7 @@ Use **cdk deploy** to deploy the stack: .. code-block:: sh - cdk deploy hello-cdk + cdk deploy The **deploy** command synthesizes an |CFN| template from the stack and then invokes the |CFN| create/update API to deploy it into your AWS @@ -806,7 +828,7 @@ the difference between the |cdk| app and the deployed stack: .. code-block:: sh - cdk diff hello-cdk + cdk diff The toolkit queries your AWS account for the current |CFN| template for the **hello-cdk** stack, and compares the result with the template synthesized from the app. @@ -842,3 +864,13 @@ encryption for the bucket: [1/2] UPDATE_COMPLETE_CLEANUP_IN_PROGRESS [AWS::CloudFormation::Stack] hello-cdk [2/2] UPDATE_COMPLETE [AWS::CloudFormation::Stack] hello-cdk ✅ Deployment of stack hello-cdk completed successfully + +What Next? +========== + + * Learn more about :doc:`CDK Concepts ` + * Check out the `examples directory `_ in your GitHub repository + * Learn about the rich APIs offered by the :doc:`AWS Construct Library ` + * Work directly with CloudFormation using the :doc:`AWS CloudFormation Library ` + * Come talk to us on `Gitter `_ + diff --git a/packages/aws-cdk-docs/src/index.rst b/packages/aws-cdk-docs/src/index.rst index c4f500ac349b2..94bfb88678694 100644 --- a/packages/aws-cdk-docs/src/index.rst +++ b/packages/aws-cdk-docs/src/index.rst @@ -50,7 +50,7 @@ Additional Documentation and Resources In addition to this guide, the following are other resources available to |cdk| users: * `AWS Developer blog `_ -* `Gitter Channel `_ +* `Gitter Channel `_ * `Stack Overflow `_ * `GitHub repository `_ @@ -84,5 +84,5 @@ To obtain an AWS account, go to `aws.amazon.com `_ and c AWS CloudFormation Library Examples Tools - Module Reference + Reference diff --git a/packages/aws-cdk-docs/src/reference.rst.template b/packages/aws-cdk-docs/src/reference.rst.template index 81d09a258d624..993dbc4a43ac0 100644 --- a/packages/aws-cdk-docs/src/reference.rst.template +++ b/packages/aws-cdk-docs/src/reference.rst.template @@ -15,5 +15,5 @@ Reference ######### .. toctree:: - :maxdepth: 2 + :maxdepth: 1 diff --git a/packages/aws-cdk-docs/src/tools.rst b/packages/aws-cdk-docs/src/tools.rst index 442f9d421d984..1a5e822d2b962 100644 --- a/packages/aws-cdk-docs/src/tools.rst +++ b/packages/aws-cdk-docs/src/tools.rst @@ -19,7 +19,7 @@ Command-line Toolkit (cdk) -------------------------- -``cdk`` (the |toolkit|) is the main tool you use to exercise your *CDK App*. It will execute +``cdk`` (the |toolkit|) is the main tool you use to interact with your |*CDK App*|. It will execute the CDK app you have written and compiled, interrogate the application model you have defined, and produce and deploy the CloudFormation templates generated by it. @@ -40,7 +40,6 @@ this option in a file called *cdk.json*: "app": "node bin/main.js" } - Below are the actions you can take on your CDK app: .. code-block:: sh @@ -86,7 +85,7 @@ Below are the actions you can take on your CDK app: If one of cdk.json or ~/.cdk.json exists, options specified there will be used as defaults. Settings in cdk.json take precedence. -.. _versionReporting: +.. _version-reporting: Version Reporting ================= @@ -108,6 +107,25 @@ The ``AWS::CDK::Metadata`` resource looks like the following: Properties: Modules: "@aws-cdk/core=0.7.2-beta,@aws-cdk/s3=0.7.2-beta,lodash=4.17.10" -Opting out of version reporting can be done by adding the -``--no-version-reporting`` argument to ``cdk`` command invocations or by setting -the ``versionReporting`` key in ``./cdk.json`` or ``~/cdk.json`` to ``false``. +.. _version-reporting-opt-out: + +Opting-out from Version Reporting + + +To out-out, use one of the following methods: + +* Use the ``--no-version-reporting`` in ``cdk`` invocations: + + .. code-block:: sh + + cdk --no-version-reporting synth + +* Set ``versionReporting`` to ``false`` in **./cdk.json** or **~/cdk.json**: + + .. code-block:: js + + { + "app": "...", + "versionReporting": false + } +