From c7e25d805b868f9fa4421d246247350720e6a041 Mon Sep 17 00:00:00 2001 From: Elad Ben-Israel Date: Sun, 8 Jul 2018 05:44:20 -0700 Subject: [PATCH 1/3] Java Getting Started (+ rewrite without "cdk init") Add getting started and welcome in Java (and JavaScript). Rewrite "Getting Started" to detail the process of defining CDK apps without using `cdk init`. This is in order to improve the understanding of users when they onboard the CDK, which fixes #219. Fix TOC to include only two layers deep which fixes #129. --- packages/@aws-cdk/cloudwatch/README.md | 18 +- packages/@aws-cdk/rtv/README.md | 2 +- packages/aws-cdk-docs/src/getting-started.rst | 928 +++++++++++++----- packages/aws-cdk-docs/src/index.rst | 7 +- packages/aws-cdk-docs/src/welcome.rst | 27 +- 5 files changed, 742 insertions(+), 240 deletions(-) diff --git a/packages/@aws-cdk/cloudwatch/README.md b/packages/@aws-cdk/cloudwatch/README.md index 6818a3661ab0f..abc1de4b205e0 100644 --- a/packages/@aws-cdk/cloudwatch/README.md +++ b/packages/@aws-cdk/cloudwatch/README.md @@ -1,8 +1,4 @@ -Add alarms and graphs to CDK applications -========================================= - -Metric objects --------------- +## Metrics Metric objects represent a metric that is emitted by AWS services or your own application, such as `CPUUsage`, `FailureCount` or `Bandwidth`. @@ -19,8 +15,7 @@ represents the amount of errors reported by that Lambda function: const errors = lambda.metricErrors(); ``` -Aggregation ------------ +### Aggregation To graph or alarm on metrics you must aggregate them first, using a function like `Average` or a percentile function like `P99`. By default, most Metric objects @@ -63,8 +58,7 @@ useful when embedding them in graphs, see below). > happen to know the Metric you want to alarm on makes sense as a rate > (`Average`) you can always choose to change the statistic. -Alarms ------- +## Alarms Alarms can be created on metrics in one of two ways. Either create an `Alarm` object, passing the `Metric` object to set the alarm on: @@ -94,8 +88,7 @@ The most important properties to set while creating an Alarms are: - `evaluationPeriods`: how many consecutive periods the metric has to be breaching the the threshold for the alarm to trigger. -Making Dashboards ------------------ +## Dashboards Dashboards are set of Widgets stored server-side which can be accessed quickly from the AWS console. Available widgets are graphs of a metric over time, the @@ -168,8 +161,7 @@ dashboard.add(new TextWidget({ })); ``` -Dashboard Layout ----------------- +### Dashboard Layout The widgets on a dashboard are visually laid out in a grid that is 24 columns wide. Normally you specify X and Y coordinates for the widgets on a Dashboard, diff --git a/packages/@aws-cdk/rtv/README.md b/packages/@aws-cdk/rtv/README.md index fd6de3b8a2eb9..2b8acd360a060 100644 --- a/packages/@aws-cdk/rtv/README.md +++ b/packages/@aws-cdk/rtv/README.md @@ -1,4 +1,4 @@ -# Runtime Values +## Runtime Values The CDK allows apps to advertise values from __construction time__ to __runtime code__. For example, consider code in a Lambda function which needs to know the diff --git a/packages/aws-cdk-docs/src/getting-started.rst b/packages/aws-cdk-docs/src/getting-started.rst index 515920ead3d8d..098a290ecaf16 100644 --- a/packages/aws-cdk-docs/src/getting-started.rst +++ b/packages/aws-cdk-docs/src/getting-started.rst @@ -8,286 +8,776 @@ either express or implied. See the License for the specific language governing permissions and limitations under the License. -.. note:: These instructions are only for the Amazon-internal preview of the |cdk|. - .. _getting_started: -############################## -Getting Started With the |cdk| -############################## +############# +Hello, |cdk|! +############# + +This topic will walk you through creating and deploying your first CDK app. -This topic provides information for those getting started with the |cdk-long| (|cdk|). +The following instructions assume that you have already installed the CDK on +your system. To verify, run the following command to verify that the installed +version matches the version of this guide (|cdk-version|): -.. _hello_cdk: +.. code-block:: sh -Hello, CDK! -=========== + cdk --version -Let's use the |cdk| to create an |CFN| an |SQS| queue, an |SNS| topic, a subscription between the topic and the queue, -and an |IAM| policy document that enables the -topic to send messages to the queue. +Initialize the project +---------------------- -.. _create_dirs: +In this section we will create an empty project structure for your CDK app. -Create Your Project Structure -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. tabs:: -Use **cdk init --lang** *LANGUAGE* to create a skeleton for your |cdk| project -in one of the supported programming languages. -For the examples in this section we'll use TypeScript. + .. group-tab:: JavaScript -.. code-block:: sh + Create an empty source-controlled directory for your project and an + initial npm **package.json** file: + + .. code-block:: sh + + mkdir hello-cdk + cd hello-cdk + git init + npm init -y + + .. group-tab:: TypeScript + + Create an empty source-controlled directory for your project and an + initial npm **package.json** file: + + .. code-block:: sh + + mkdir hello-cdk + cd hello-cdk + git init + npm init -y # creates package.json + + Create a minimal **tsconfig.json**: + + .. code-block:: json + + { + "compilerOptions": { + "target": "es2018", + "module": "commonjs" + } + } + + Setup TypeScript build commands in **package.json**: + + .. code-block:: json + + { + "scripts": { + "build": "tsc", + "watch": "tsc -w" + } + } + + .. group-tab:: Java + + Use your favorite IDE to create a Maven-based empty Java 8 project. + + Set the Java **source** and **target** to 1.8 in your **pom.xml** file: + + .. code-block:: xml + + + + + + org.apache.maven.plugins + maven-compiler-plugin + 3.1 + + 1.8 + 1.8 + + + + + +Add @aws-cdk/core as a dependency +--------------------------------- + +Now, we will install the CDK core library (:py:mod:`_aws-cdk_core`). This +library includes the basic classes needed to write CDK stacks and apps. + +.. tabs:: + + .. group-tab:: JavaScript + + Use **y-npm** to install the **@aws-cdk/core** package: + + .. code-block:: sh + + y-npm install @aws-cdk/core + + .. note:: We are using **y-npm** instead of **npm** in order to install npm + modules from the local npm repository included with your CDK + installation. These instructions will change once the CDK will be + published publically. - mkdir hello-cdk - cd hello-cdk - cdk init --language=typescript - -The **cdk init** command creates the following: - -* *bin* contains the following files. The command creates *hello-cdk.ts* from a template, - and the other two files as it runs the TypeScript compiler: - - * *hello-cdk.d.ts* - * *hello-cdk.js* - * *hello-cdk.ts* is TypeScript source for the entry point to your app - (the file we'll update later) - -* *cdk.json* specifies the entry point to your app, - so that you can omit the **--app** option, - such as when running **cdk synth** -* *node_module* contains the Node packages you need to develop your TypeScript source -* *package.json* contains metadata for the app. -* *package-lock.json* is the npm lockfile for package.json -* *README.md* contains some information to help you from this point on -* *tsconfig.json* contains definitions for the TypeScript compiler - -The command displays README.md as it finishes to give you information about some useful commands. - -Let's take a look at an annotated version of the file *hello-cdk.ts*. - -.. note:: You can use an IDE, such as - `Microsoft Visual Code `_, - `Sublime Text `_ with the - `Sublime TypeScript `_ plugin, or - `Atom `_ with the - `Atom TypeScript `_ plugin, - to get auto-completion in your Typescript code. - -Replace the contents of the file *hello-cdk.ts* with the following code to create a class that -extends **Stack**, and include some construction logic. - -.. code-block:: js - - // You'll need this statement in every app - import { App, Stack, StackProps } from '@aws-cdk/core'; - - // The SNS resources, such as Topic, are defined in @aws-cdk/sns - import { Topic } from '@aws-cdk/sns'; - - // The SQS resources, such as Queue, are defined in @aws-cdk/sqs - import { Queue } from '@aws-cdk/sqs'; - - class HelloStack extends Stack { - // Instantiate HelloStack with a reference to its parent, - // as it might need some context; - // as it might need some context from the app; - // a name; and some optional properties. - // You'll almost always use these same two lines. - constructor(parent: App, name: string, props?: StackProps) { - super(parent, name, props); - - // Create an SNS topic - const topic = new Topic(this, 'MyTopic'); - - // Create an SQS queue - const queue = new Queue(this, 'MyQueue', { - // By default you only get 30 seconds to delete a read message after you've read it; - // otherwise it becomes available to other consumers. - // This extends that duration to 5 minutes. - visibilityTimeoutSec: 300 - }); - - // Subscribe the topic to the queue - topic.subscribeQueue(queue); + .. group-tab:: TypeScript + + Use **y-npm** to install the **@aws-cdk/core** package. We also need **@types/node** + since we will be using **process.argv** in our code: + + .. code-block:: sh + + y-npm install @aws-cdk/core @types/node + + .. note:: We are using **y-npm** instead of **npm** in order to install npm + modules from the local npm repository included with your CDK + installation. These instructions will change once the CDK will be + published publically. + + .. group-tab:: Java + + Add the following to your project's `pom.xml` file: + + .. code-block:: xml + + + + + cdk + file:///${env.HOME}/.cdk/repo/maven + + + + + + com.amazonaws.cdk + aws-cdk + + + 0.7.3-beta + + + + .. note:: The **** section is only needed during private Beta. + +Define your CDK app +------------------- + +CDK apps are modeled as classes which extend the :py:class:`_aws-cdk_core.App` +class. Let's create our first, empty **App**: + +.. tabs:: + + .. code-tab:: js + + // index.js + + const cdk = require('@aws-cdk/core'); + + class MyFirstApp extends cdk.App { + constructor(argv) { + super(argv); + } + } + + process.stdout.write(new MyFirstApp(process.argv).run()); + + .. code-tab:: ts + + // index.ts + + import * as cdk from '@aws-cdk/core'; + + class MyFirstApp extends cdk.App { + constructor(argv: string[]) { + super(argv); + } } - } - // Create a new App and associate the HelloStack stack with it. - const app = new App(process.argv); - new HelloStack(app, 'hello-cdk'); + process.stdout.write(new MyFirstApp(process.argv).run()); + + .. code-tab:: java + + // src/main/java/com/acme/MyApp.java + + package com.acme; + + import com.amazonaws.cdk.App; - // Boilerplate to produce the CloudFormation template - process.stdout.write(app.run()); + import java.util.Arrays; + import java.util.List; -.. _compile: + public class MyApp extends App { + public MyApp(final List argv) { + super(argv); + } -Compiling the App + public static void main(final String[] argv) { + System.out.println(new MyApp(Arrays.asList(argv)).run()); + } + } + +.. note:: The code that reads **argv**, runs the app and writes the output to **STDOUT** is + currently needed in order to allow the CDK Toolkit to interact with your app. In the future + the toolkit will include per-language shims that will remove this boilerplate. + +Compile your code ----------------- -Use the command for your programming language in the following table to compile your app. -You must compile your app every time you change it. +If needed, compile the code: + +.. tabs:: + + .. group-tab:: JavaScript + + No need to compile + + .. group-tab:: TypeScript + + To compile your program from **.ts** to **.js**: + + .. code-block:: sh + + npm run build + + You can also use the **watch** command to continuously compile your code + as it changes, so you don't have to invoke the compiler explicitly: + + .. code-block:: sh + + # run in another terminal session + npm run watch + + .. group-tab:: Java -.. list-table:: - :widths: 1 2 - :header-rows: 1 + Compile your code using your IDE or via the command line via **mvn**: - * - Language - - Compilation Command + .. code-block:: sh - * - TypeScript - - **npm run prepare** - (use **npm run watch** in a separate command window to watch for source changes and automatically recompile) + mvn compile -.. _create_cloud_formation: +This is it, you now created your first, alas empty, CDK app. -Synthesizing a CloudFormation Template +Configure CDK toolkit via **cdk.json** -------------------------------------- -Use the **cdk synth** command to synthesize an |CFN| template for a stack in your app. -You do not need to synthesize your |CFN| template to deploy it. +We will now use the CDK toolkit to view the contents of this app. -.. code-block:: console +.. note:: - cdk synth + You must specify your default credentials and region to use the toolkit, -You should see output similar to the following: + Use the `AWS Command Line Interface `_ + ``aws configure`` command to specify your default credentials and region. -.. code-block:: yaml + Important: make sure that you explicitly specify a **region**. - Resources: - MyTopic86869434: - Type: 'AWS::SNS::Topic' - MyTopicMyQueueSubscription3245B11E: - Type: 'AWS::SNS::Subscription' - Properties: - Endpoint: - 'Fn::GetAtt': - - MyQueueE6CA6235 - - Arn - Protocol: sqs - TopicArn: - Ref: MyTopic86869434 - MyQueueE6CA6235: - Type: 'AWS::SQS::Queue' - Properties: - VisibilityTimeout: 300 - MyQueuePolicy6BBEDDAC: - Type: 'AWS::SQS::QueuePolicy' - Properties: - PolicyDocument: - Statement: - - - Action: 'sqs:SendMessage' - Condition: - ArnEquals: - 'aws:SourceArn': - Ref: MyTopic86869434 - Effect: Allow - Principal: - Service: sns.amazonaws.com - Resource: - 'Fn::GetAtt': - - MyQueueE6CA6235 - - Arn - Version: '2012-10-17' - Queues: - - - Ref: MyQueueE6CA6235 - -As you can see, the call to :py:meth:`_aws-cdk_sns.TopicRef.subscribeQueue` on -the :py:class:`_aws-cdk_sns.Topic` resulted in: - -1. Creating an **AWS::SNS::Subscription** associated with the queue and the topic. -2. Adding a statement to the **AWS::SQS::QueuePolicy**, which allows the topic to send messages to the queue. - -.. _deploy_your_stack: - -Deploying Your Stack ---------------------- - -Use **cdk deploy** to deploy the stack. As **cdk deploy** executes you -should see information messages, such as feedback from CloudFormation logs. + You can also set environment variables for your default credentials and region. + Environment variables take precedence over settings in the credentials or config file. -.. code-block:: sh + * *AWS_ACCESS_KEY_ID* specifies your access key + * *AWS_SECRET_ACCESS_KEY* specifies your secret access key + * *AWS_DEFAULT_REGION* specifies your default region + + See `Environment Variables `_ + in the CLI User Guide for details. + +The CDK toolkit needs to know how to execute your CDK app. It requires that the +:code:`--app` command-line option will point to an executable program that adhere's +to the toolkit's protocol (this is what the **ARGV/STDOUT** boilerplate +implements). Alternatively to explicitly specifying :code:`--app` every time you use +the toolkit, we recommend that you create a :code:`cdk.json` file at the root of +your project directory: + +.. tabs:: + + .. group-tab:: JavaScript + + Define the :code:`--app` option in **cdk.json** to execute **index.js** + using **node**: + + .. code-block:: json + + { + "app": "node index.js" + } + + .. group-tab:: TypeScript + + Define the :code:`--app` option in **cdk.json** to execute **index.js** + using **node**: + + .. code-block:: json + + { + "app": "node index.js" + } + + .. group-tab:: Java - cdk deploy + In order to execute our Java program, we will need to specify a + **CLASSPATH** which contains both our compiled code and dependencies. + We will use **maven-dependency-plugin** to produce a file **.classpath.txt** + whenever the project is compiled: -.. note:: You must specify your default credentials and region to use the **cdk deploy** command, - unless you explicitly set them when you create a stack. - The following examples creates a stack for account *ACCOUNT* in the region *REGION*. + .. code-block:: xml - :code:`new MyStack(app, { env: { region: 'REGION', account: 'ACCOUNT' } });` + - Use the `AWS Command Line Interface `_ - ``aws configure`` command to specify your default credentials and region. - - Important: make sure that you explicitly specify a **region**. + + + -.. You can also set environment variables for your default credentials and region. - Environment variables take precedence over settings in the credentials or config file. + + + org.apache.maven.plugins + maven-dependency-plugin + 2.8 + + + build-classpath + generate-sources + + build-classpath + + + .classpath.txt + + + + + + - * *AWS_ACCESS_KEY_ID* specifies your access key - * *AWS_SECRET_ACCESS_KEY* specifies your secret access key - * *AWS_DEFAULT_REGION* specifies your default region + Run **mvn compile** and verify the **.classpath.txt** exist: - See `Environment Variables `_ - in the CLI User Guide for details. + .. code-block:: sh -.. _making_changes: + mvn compile + ls .classpath.txt -Making Changes + Now, create a shim **app.sh** which will be used to execute our CDK Java app: + + .. code-block:: sh + + #!/bin/bash + exec java -cp target/classes:$(cat .classpath.txt) com.acme.MyApp app $@ + + And now we can define the :code:`-- app` option in **cdk.json**: + + .. code-block:: json + + { + "app": "/bin/bash ./app.sh" + } + +List all stacks in your app +--------------------------- + +To list the stacks in this app, you can use the CDK toolkit's **ls** command. + +.. code-block:: sh + + cdk ls + +The result will be quite disappointing: + +.. code-block:: sh + + [] + +An empty array, which makes sense, since our app still doesn't have any stacks +in it. + +Define a stack -------------- -Let's change the visibility timeout of the queue from 300 to 500. +Now, let's define our first stack and add it to our app. + +.. tabs:: + + .. code-tab:: js + :emphasize-lines: 4,5,6,7,8,14 + + // index.js + const cdk = require('@aws-cdk/core'); + + class MyFirstStack extends cdk.Stack { + constructor(parent, id, props) { + super(parent, id, props); + } + } + + class MyFirstApp extends cdk.App { + constructor(argv) { + super(argv); + + new MyFirstStack(this, 'hello-cdk'); + } + } + + process.stdout.write(new MyFirstApp(process.argv).run()); + + .. code-tab:: ts + :emphasize-lines: 4,5,6,7,8,14 + + // index.ts + import * as cdk from '@aws-cdk/core'; + + class MyFirstStack extends cdk.Stack { + constructor(parent: cdk.App, id: string, props?: cdk.StackProps) { + super(parent, id, props); + } + } + + class MyFirstApp extends cdk.App { + constructor(argv: string[]) { + super(argv); + + new MyFirstStack(this, 'hello-cdk'); + } + } -.. code-block:: javascript + process.stdout.write(new MyFirstApp(process.argv).run()); - const queue = new Queue(this, 'MyQueue', { - visibilityTimeoutSec: 500 - }); + .. code-tab:: java + :emphasize-lines: 1,2,3,4,5,6,7,8,9,10,11,25 -Compile your app with **npm run prepare** if you aren't running **npm run watch** in a separate window. + // src/main/java/com/acme/MyStack.java + + package com.acme; + + import com.amazonaws.cdk.App; + import com.amazonaws.cdk.Stack; + + public class MyStack extends Stack { + public MyStack(final App parent, final String id) { + super(parent, id); + } + } + + // src/main/java/com/acme/MyApp.java + package com.acme; + + import com.amazonaws.cdk.App; + + import java.util.Arrays; + import java.util.List; + + public class MyApp extends App { + public MyApp(final List argv) { + super(argv); + + new MyStack(this, "hello-cdk"); + } + + public static void main(final String[] argv) { + System.out.println(new MyApp(Arrays.asList(argv)).run()); + } + } -If you've deployed your stack previously, -run the following command to see the difference between the *deployed* stack and your |cdk| project -(if you haven't deployed the stack, you won't see any output): +The initializer signature of **cdk.Stack** includes three arguments: **parent**, +**id** and **props**. This is the signature for every class in the CDK +framework. These classes are called **"constructs"** and they are composed +together to 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 identifier of the construct within the tree. + Constructs must have a unique ID amongst their siblings. +* **props** is the set of initialization properties for this construct. + +Compile your program: + +.. tabs:: + + .. group-tab:: JavaScript + + Nothing to compile. + + .. group-tab:: TypeScript + + .. code-block:: sh + + npm run build + + .. group-tab:: Java + + .. code-block:: sh + + mvn compile + + +Now, when we run **cdk ls**, the result shows that your app includes a single +stack: .. code-block:: sh - # compile your code (depends on your language) - cdk diff + cdk ls # don't forget to compile your project first! + - + name: hello-cdk + environment: + name: / + account: '' + region: + +Notice that your stack has been automatically associated with the default AWS +account and region configured in the AWS CLI. + +Define an S3 bucket +------------------- + +Now, what can we do with this app? Nothing yet. Our stack is still empty so, +there's nothing to deploy. + +Let's define an S3 bucket. + +First, we need to install the **@aws-cdk/s3** package: + +.. tabs:: + + .. group-tab:: JavaScript + + .. code-block:: sh + + y-npm install @aws-cdk/s3 + + .. group-tab:: TypeScript + + .. code-block:: sh + + y-npm install @aws-cdk/s3 + + .. group-tab:: Java + + During beta, we bundled all CDK modules into the aws-cdk Maven package, so + there is no need to explicitly install the S3 library. + +Now, let's define an S3 bucket in our stack. S3 buckets are represented by +the :py:class:`_aws-cdk_s3.Bucket` class: + +.. tabs:: + + .. code-tab:: js + :emphasize-lines: 3,9,10,11 + + // index.js + const cdk = require('@aws-cdk/core'); + const s3 = require('@aws-cdk/s3'); + + class MyFirstStack extends cdk.Stack { + constructor(parent, id, props) { + super(parent, id, props); + + new s3.Bucket(this, 'MyFirstBucket', { + versioned: true + }); + } + } + + .. code-tab:: ts + :emphasize-lines: 3,9,10,11 + + // index.ts + import * as cdk from '@aws-cdk/core'; + import * as s3 from '@aws-cdk/s3'; + + class MyFirstStack extends cdk.Stack { + constructor(parent: cdk.App, id: string, props?: cdk.StackProps) { + super(parent, id, props); + + new s3.Bucket(this, 'MyFirstBucket', { + versioned: true + }); + } + } + + .. code-tab:: java + :emphasize-lines: 6,7,13,14,15 + + // src/main/java/com/acme/MyStack.java + package com.acme; + + import com.amazonaws.cdk.App; + import com.amazonaws.cdk.Stack; + import com.amazonaws.cdk.s3.Bucket; + import com.amazonaws.cdk.s3.BucketProps; -You should see something like the following. + public class MyStack extends Stack { + public MyStack(final App parent, final String id) { + super(parent, id); + + new Bucket(this, "MyFirstBucket", BucketProps.builder() + .withVersioned(true) + .build()); + } + } + +A few things to notice: + +* **s3.Bucket** is construct. This means it's initialization signature will have + **parent**, **id** and **props**. In this case, the bucket is an immediate + child of **MyStack**, it's id is 'MyFirstBucket'. +* We configured out bucket to have versioning enabled by setting the + :code:`versioned` property to :code:`true`. + +Compile your program: + +.. tabs:: + + .. group-tab:: JavaScript + + Nothing to compile. + + .. group-tab:: TypeScript + + .. code-block:: sh + + npm run build + + .. group-tab:: Java + + .. code-block:: sh + + mvn compile + +Synthesize a CloudFormation template +------------------------------------ + +Now, that our stack contains a bucket, we can ask the toolkit to synthesize a +CloudFormation template for our stack (don't forget to compile your project): + +.. code-block:: sh + + cdk synth hello-cdk + +.. note:: Since our CDK app only contains a single stack, you can omit :code:`hello-cdk`. + +This command will execute our CDK app and synthesize a CloudFormation template for the +**hello-cdk** stack: + +.. code-block:: yaml + + Resources: + MyFirstBucketB8884501: + Type: 'AWS::S3::Bucket' + Properties: + VersioningConfiguration: + Status: Enabled + +You can see that the stack contains an **AWS::S3::Bucket** resource with the desired +versioning configuration. + +Deploying our stack +------------------- + +To deploy our stack, use **cdk deploy**: .. code-block:: sh - [~] 🛠 Updating HelloCdkPbQueue8837C78B (type: AWS::SQS::Queue) - └─ [~] .VisibilityTimeout: - ├─ [-] Old value: 300 - └─ [+] New value: 500 + cdk deploy hello-cdk + +The **deploy** command will synthesize a CloudFormation template from your stack +and then invoke the CloudFormation create/update API to deploy it into your AWS +account. Progress will be emitted to your console. -If the changes are acceptable, run **cdk deploy** to update your -infrastructure. +Modifying your code +------------------- -Let's make a bigger change by adding an |S3| bucket to our stack. -Run the following command to install the |S3| package. +Let's configure our bucket to use KMS managed encryption: + +.. tabs:: + + .. code-tab:: js + :emphasize-lines: 3 + + new s3.Bucket(this, 'MyFirstBucket', { + versioned: true, + encryption: s3.BucketEncryption.KmsManaged + }); + + + .. code-tab:: ts + :emphasize-lines: 3 + + new s3.Bucket(this, 'MyFirstBucket', { + versioned: true, + encryption: s3.BucketEncryption.KmsManaged + }); + + .. code-tab:: java + :emphasize-lines: 3 + + new Bucket(this, "MyFirstBucket", BucketProps.builder() + .withVersioned(true) + .withEncryption("MANAGED") + .build()); + +Compile your program: + +.. tabs:: + + .. group-tab:: JavaScript + + Nothing to compile. + + .. group-tab:: TypeScript + + .. code-block:: sh + + npm run build + + .. group-tab:: Java + + .. code-block:: sh + + mvn compile + +Preparing for deployment using **cdk diff** +------------------------------------------- + +Before we deploy our updated stack, we can use the **cdk diff* command to evaluate +the difference between our CDK app and the deployed stack: + +.. code-block:: sh + + cdk diff hello-cdk + +The toolkit will query your AWS account for the current CloudFormation template for the +**hello-cdk** stack, and will compare the result with the template synthesized from your app. +The output should look like this: .. code-block:: sh - npm install @aws-cdk/s3 + [~] 🛠 Updating MyFirstBucketB8884501 (type: AWS::S3::Bucket) + └─ [+] .BucketEncryption: + └─ New value: {"ServerSideEncryptionConfiguration":[{"ServerSideEncryptionByDefault":{"SSEAlgorithm":"aws:kms"}}]} -Add the following to the top of *hello-cdk.ts* (we recommend you keep your import statements sorted): +As you can see, the diff indicates that the +**ServerSideEncryptionConfiguration** property of the bucket is now set to +enable server-side encryption. -.. code-block:: js +You can also that the bucket is not going to be replaced but rather updated +("**Updating MyFirstBucketB8884501**"). - import { Bucket } from '@aws-cdk/s3'; +Now, run **cdk deploy** to update your stack: -Finally, create a bucket by adding the following to your constructor. -Don't forget that |S3| has restrictions on bucket names. -See `Rules for Bucket Naming `_. +.. code-block:: sh -.. code-block:: js + cdk deploy + +The toolkit will update your bucket configuration to enable server-side KMS +encryption for your bucket: + +.. code-block:: sh - new Bucket(this, "MyBucket", { - bucketName: "mygroovybucket" - }) + ⏳ Starting deployment of stack hello-cdk... + [0/2] UPDATE_IN_PROGRESS [AWS::S3::Bucket] MyFirstBucketB8884501 + [1/2] UPDATE_COMPLETE [AWS::S3::Bucket] MyFirstBucketB8884501 + [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 diff --git a/packages/aws-cdk-docs/src/index.rst b/packages/aws-cdk-docs/src/index.rst index 9f3d8ad002cbc..cd275642c4a3b 100644 --- a/packages/aws-cdk-docs/src/index.rst +++ b/packages/aws-cdk-docs/src/index.rst @@ -15,15 +15,16 @@ User Guide ########## .. toctree:: + :maxdepth: 2 + Welcome Getting Started - Developing Libraries - Examples Concepts + Examples Tools Advanced Topics Glossary - Reference + AWS Construct Library .. Removed on 6/20/2018: Developing Apps (see https://github.com/awslabs/aws-cdk/pull/142) .. Incorporated into concepts: l1-vs-l2 diff --git a/packages/aws-cdk-docs/src/welcome.rst b/packages/aws-cdk-docs/src/welcome.rst index 2099f673d60c4..4573e01d79cca 100644 --- a/packages/aws-cdk-docs/src/welcome.rst +++ b/packages/aws-cdk-docs/src/welcome.rst @@ -30,14 +30,33 @@ in :doc:`getting-started`. .. tabs:: + .. code-tab:: js + + const cdk = require('@aws-cdk/core'); + const sqs = require('@aws-cdk/sqs'); + const sns = require('@aws-cdk/sns'); + + class HelloStack extends cdk.Stack { + constructor(parent, id, props) { + super(parent, id, props); + + const topic = new Topic(this, 'MyTopic'); + const queue = new Queue(this, 'MyQueue', { + visibilityTimeoutSec: 300 + }); + + topic.subscribeQueue(queue); + } + } + .. code-tab:: ts - import { App, Stack, StackProps } from '@aws-cdk/core'; + import * as cdk from '@aws-cdk/core'; import { Topic } from '@aws-cdk/sns'; import { Queue } from '@aws-cdk/sqs'; - class HelloStack extends Stack { - constructor(parent: App, name: string, props?: StackProps) { + class HelloStack extends cdk.Stack { + constructor(parent: App, name: string, props?: cdk.StackProps) { super(parent, name, props); const topic = new Topic(this, 'MyTopic'); @@ -76,7 +95,7 @@ in :doc:`getting-started`. The process of creating your AWS resources using the |cdk| is straightforward: -1. Install the |cdk| on your development machine +1. Install the |cdk| on your development machine (see setup instructions in README). 2. Run the **cdk init** command to create the skeleton of your program in one of the supported programming languages 3. Use your favorite development environment to define your AWS application infrastructure From b611c502d9328c3031634d5cdb448145babd3cfb Mon Sep 17 00:00:00 2001 From: Elad Ben-Israel Date: Sun, 8 Jul 2018 13:14:17 -0700 Subject: [PATCH 2/3] Change note at the beginning of the section --- packages/aws-cdk-docs/src/getting-started.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/packages/aws-cdk-docs/src/getting-started.rst b/packages/aws-cdk-docs/src/getting-started.rst index 098a290ecaf16..e5f126bab392b 100644 --- a/packages/aws-cdk-docs/src/getting-started.rst +++ b/packages/aws-cdk-docs/src/getting-started.rst @@ -8,6 +8,9 @@ either express or implied. See the License for the specific language governing permissions and limitations under the License. +.. note:: Some of the instructions in this topic will change when the CDK will be published + to the public package repositories. + .. _getting_started: ############# From ce096ddca6af1ce28d55ed839c0c49f606361345 Mon Sep 17 00:00:00 2001 From: Elad Ben-Israel Date: Mon, 9 Jul 2018 01:10:03 -0700 Subject: [PATCH 3/3] Rephrase a little --- packages/aws-cdk-docs/src/welcome.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/aws-cdk-docs/src/welcome.rst b/packages/aws-cdk-docs/src/welcome.rst index 4573e01d79cca..79b9fddab8985 100644 --- a/packages/aws-cdk-docs/src/welcome.rst +++ b/packages/aws-cdk-docs/src/welcome.rst @@ -95,7 +95,7 @@ in :doc:`getting-started`. The process of creating your AWS resources using the |cdk| is straightforward: -1. Install the |cdk| on your development machine (see setup instructions in README). +1. Follow the setup instructions to Install the |cdk| on your development machine. 2. Run the **cdk init** command to create the skeleton of your program in one of the supported programming languages 3. Use your favorite development environment to define your AWS application infrastructure