Skip to content

Commit

Permalink
docs: Updates to the CloudFormation topic and reference cdk-init in G…
Browse files Browse the repository at this point in the history 
…etting Started (#414)

* Align to new library organization and improve 
accuracy of descriptions and terminology.
* Added a note about cdk init in getting started
  • Loading branch information
Elad Ben-Israel authored Jul 26, 2018
1 parent 0543402 commit 071d5d2
Show file tree
Hide file tree
Showing 2 changed files with 95 additions and 41 deletions.
128 changes: 87 additions & 41 deletions packages/aws-cdk-docs/src/cloudformation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,64 +8,107 @@
either express or implied. See the License for the specific language governing permissions and
limitations under the License.
.. _advanced_topics:
.. _cloudformation:

###############
Advanced Topics
###############
############################
The AWS CloudFormation Layer
############################

This section includes information about |cdk| features that most developers do not use.
AWS construct libraries (such as :py:mod:`@aws-cdk/aws-s3`) include constructs
that offer rich APIs for defining AWS infrastructure. For example, the
:py:class:`@aws-cdk/aws-s3.Bucket` construct can be used to define S3 Buckets,
the :py:class:`@aws-cdk/aws-sns.Topic` construct can be used to define SNS
Topics, etc.

.. _creating_l1_constructs:
Under the hood, these constructs are implemented using CloudFormation resources,
which are available under the **cloudformation** namespace of each library. For
example, the :py:class:`@aws-cdk/aws-s3.Bucket` construct uses the
:py:class:`@aws-cdk/aws-s3.cloudformation.BucketResource` resource (as well as
other resources, depending on what bucket APIs are used).

Creating |l1| Constructs
.. important::

Generally, when building CDK apps, you shouldn't need to interact
CloudFormation directly. However, there might be advanced use cases and
migration scenarios where this might be required. We are also aware that
there might be gaps in capabilities in the AWS Construct Library over time.

CloudFormation Resources
========================

|l1| constructs are found in the :py:mod:`@aws-cdk/resources` package. They map directly onto |cfn|
resources.
CloudFormation resource classes are automatically generated from the `AWS
CloudFormation Resource Specification
<https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-resource-specification.html>`_
and available under the **cloudformation** namespace of each AWS library. Their
API matches 1:1 with how you would use these resources in CloudFormation.

.. important::
When defining CloudFormation resource, the **props** argument of the class
initializer will match 1:1 to the resource's properties in CloudFormation.

For example, to define an
`AWS::SQS::Queue <https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-sqs-queues.html>`_
resource encrypted with an AWS managed key you can directly specify the
`KmsMasterKeyId <https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-sqs-queues.html#aws-sqs-queue-kmsmasterkeyid>`_
property.

.. code-block:: js
import { cloudformation } from '@aws-cdk/aws-sqs';
new cloudformation.QueueResource(this, 'MyQueueResource', {
kmsMasterKeyId: 'alias/aws/sqs'
});
For reference, if you use the :py:class:`@aws-cdk/aws-sqs.Queue` construct, you
can define managed queue encryption as follows:

.. code-block:: js
import sqs = require('@aws-cdk/aws-sqs');
new sqs.Queue(this, 'MyQueue', {
encryption: sqs.QueueEncryption.KmsManaged
});
In general, you shouldn't need to use this type of Constructs, unless you have
special requirements or there is no Construct Library for the AWS resource you
need yet. You should use other packages with higher-level constructs instead.
.. _construct_attributes:

Construct Attributes
--------------------
Resource Attributes
-------------------

To reference the runtime attributes of constructs,
use one of the properties available on the construct object.
To reference the runtime attributes of CloudFormation resources,
use one of the properties available on the resource object.

The following example configures a |LAM| function's dead letter queue to use a
the ARN of an |SQS| queue resource.

.. code-block:: js
import { lambda, sqs } from '@aws-cdk/resources'
import { cloudformation as sqscfn } from '@aws-cdk/aws-sqs';
import { cloudformation as lambdacfn } from '@aws-cdk/aws-lambda';
const dlq = new sqs.QueueResource(this, { name: 'DLQ' });
const dlq = new sqscfn.QueueResource(this, { name: 'DLQ' });
new lambda.FunctionResource(this, {
new lambdacfn.FunctionResource(this, {
deadLetterConfig: {
targetArn: dlq.queueArn
}
});
The :py:attr:`aws-cdk.Resource.ref` attribute represents the |cfn|
resource's intrinsic reference (or "Return Value"). For example, for `queue.ref`
will also `refer <http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-sqs-queues.html#aws-properties-sqs-queues-ref>`_
to the queue's ARN. If possible, it is preferrable to use an explicitly
named attribute instead of *ref*.
The :py:attr:`@aws-cdk/cdk.Resource.ref` attribute represents the |cfn|
resource's intrinsic reference (or "Return Value"). For example, for `dlq.ref`
will also `refer
<http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-sqs-queues.html#aws-properties-sqs-queues-ref>`_
to the queue's ARN. When possible, it is preferrable to use an explicitly named
attribute instead of *ref*.

.. _resource_options:

Resource Options
----------------

The :py:attr:`aws-cdk.Resource.options` object includes |CFN| options, such as
:code:`condition`, :code:`updatePolicy`, :code:`createPolicy` and
The :py:attr:`@aws-cdk/cdk.Resource.options` object includes |CFN| options, such
as :code:`condition`, :code:`updatePolicy`, :code:`createPolicy` and
:code:`metadata`, for a resource.

.. _parameters:
Expand All @@ -77,10 +120,11 @@ Parameters
.. code-block:: js
import { Parameter } from '@aws-cdk/cdk';
import { cloudformation } from '@aws-cdk/aws-sns';
import cdk = require('@aws-cdk/cdk');
const p = new Parameter(this, 'MyParam', { type: 'String' });
new sns.TopicResource(this, 'MyTopic', { displayName: p.ref });
const p = new cdk.Parameter(this, 'MyParam', { type: 'String' });
new cloudformation.TopicResource(this, 'MyTopic', { displayName: p.ref });
.. _outputs:

Expand All @@ -91,10 +135,11 @@ Outputs
.. code-block:: js
import { Output } from '@aws-cdk/cdk';
import { cloudformation } from '@aws-cdk/aws-sqs';
import cdk = require('@aws-cdk/cdk');
const queue = new sqs.QueueResource(this, 'MyQueue');
const out = new Output(this, 'MyQueueArn', { value: queue.queueArn });
const queue = new cloudformation.QueueResource(this, 'MyQueue');
const out = new cdk.Output(this, 'MyQueueArn', { value: queue.queueArn });
const import = out.makeImportValue();
assert(import === { "Fn::ImportValue": out.exportName }
Expand All @@ -108,12 +153,13 @@ Conditions
.. code-block:: js
import { Condition } from '@aws-cdk/cdk';
const cond = new Condition(this, 'MyCondition', {
expression: new FnIf(...)
import { cloudformation } from '@aws-cdk/aws-sqs';
import cdk = require('@aws-cdk/cdk');
const cond = new cdk.Condition(this, 'MyCondition', {
expression: new cdk.FnIf(...)
});
const queue = new sqs.QueueResource(this, 'MyQueue');
const queue = new cloudformation.QueueResource(this, 'MyQueue');
queue.options.condition = cond;
.. _intrinsic_functions:
Expand All @@ -125,8 +171,8 @@ Intrinsic Functions
.. code-block:: js
import { FnJoin } from '@aws-cdk/cdk';
new FnJoin(",", ...)
import cdk = require('@aws-cdk/cdk');
new cdk.FnJoin(",", ...)
.. _pseudo_parameters:
Expand All @@ -137,8 +183,8 @@ Pseudo Parameters
.. code-block:: js
import { AwsRegion } from '@aws-cdk/cdk';
new AwsRegion()
import cdk = require('@aws-cdk/cdk');
new cdk.AwsRegion()
.. Add a new topic in "Advanced Topics" about integrating
cdk synch > mytemplate
Expand Down
8 changes: 8 additions & 0 deletions packages/aws-cdk-docs/src/getting-started.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,14 @@ version matches the version of this guide (|cdk-version|):
cdk --version
.. note::

This guide walks you through the process of creating a CDK project
step-by-step as an opportunity to explain some of the reasoning and details
behind the project structure and tools. It is also possible to use the
:code:`cdk init` command to get started quickly from a project
template in supported languages.

Initialize the project
----------------------

Expand Down

0 comments on commit 071d5d2

Please sign in to comment.