From 1c79f34d24c2b88e4870881679ecf9c2f113bae2 Mon Sep 17 00:00:00 2001 From: Doug-AWS Date: Wed, 5 Dec 2018 12:38:24 -0800 Subject: [PATCH 01/10] WIP --- docs/src/apples_example.rst | 465 +++++++++++++ docs/src/ecs_example.rst | 218 ++++++ docs/src/getting-started.rst | 963 +------------------------- docs/src/index.rst | 20 +- docs/src/region-note.rst | 4 +- docs/src/tools.rst | 4 +- docs/src/tutorial.rst | 1228 ++++++++++++++++++++++++---------- 7 files changed, 1603 insertions(+), 1299 deletions(-) create mode 100644 docs/src/apples_example.rst create mode 100644 docs/src/ecs_example.rst diff --git a/docs/src/apples_example.rst b/docs/src/apples_example.rst new file mode 100644 index 0000000000000..ef2be74938b61 --- /dev/null +++ b/docs/src/apples_example.rst @@ -0,0 +1,465 @@ +.. 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. + +.. _tutorial: + +############## +|cdk| Tutorial +############## + +This topic steps you through creating the resources for a simple widget dispensing +service using the |cdk|. + +.. _overview: + +Overview +======== + +This tutorial contains the following steps. + +1. Create a |cdk| app + +2. Create a |LAMlong| function that gets a list of widgets with: GET / + +3. Create the service that calls the |LAM| function + +4. Add the service to the |cdk| app + +5. Test the app + +6. Add |LAM| functions to: + + * create an widget based with: POST /{name} + * get an widget by name with: GET /{name} + * delete an widget by name with: DELETE /{name} + +.. _create_app: + +Step 1: Create a |cdk| App +========================== + +Let's create the TypeScript app **MyWidgetService** in in the current folder. + +.. code-block:: sh + + mkdir MyWidgetService + cd MyWidgetService + cdk init --language typescript + +This creates *my_widget_service.ts* in the *bin* directory. +We don't need most of this code, +so for now change it to the following: + +.. code-block:: ts + + #!/usr/bin/env node + import cdk = require('@aws-cdk/cdk'); + + class MyWidgetServiceStack extends cdk.Stack { + constructor(parent: cdk.App, name: string, props?: cdk.StackProps) { + super(parent, name, props); + + + } + } + + // Create a new CDK app + const app = new cdk.App(); + + // Add your stack to it + new MyWidgetServiceStack(app, 'MyWidgetServiceStack'); + + app.run(); + +Save it and make sure it builds and creates an empty stack. + +.. code-block:: sh + + npm run build + cdk synth + +You should see a stack like the following, +where CDK-VERSION is the version of the CDK. + +.. code-block:: sh + + Resources: + CDKMetadata: + Type: 'AWS::CDK::Metadata' + Properties: + Modules: >- + @aws-cdk/cdk=CDK-VERSION,@aws-cdk/cx-api=CDK-VERSION,my_widget_service=0.1.0 + +.. _create_lambda_functions: + +Step 2: Create a |LAM| Function to List all Widgets +=================================================== + +The next step is to create a |LAM| function to list all of the widgets in our +|S3| bucket. + +Create the directory *resources* at the same level as the *bin* directory. + +.. code-block:: sh + + mkdir resources + +Create the following Javascript file, *widgets.js*, +in the *resources* directory. + +.. code-block:: js + + const AWS = require('aws-sdk'); + const S3 = new AWS.S3(); + + const bucketName = process.env.BUCKET; + + exports.main = async function(event, context) { + try { + var method = event.httpMethod; + + if (method === "GET") { + if (event.path === "/") { + const data = await S3.listObjectsV2({ Bucket: bucketName }).promise(); + var body = { + widgets: data.Contents.map(function(e) { return e.Key }) + }; + return { + statusCode: 200, + headers: {}, + body: JSON.stringify(body) + }; + } + } + + // We only accept GET for now + return { + statusCode: 400, + headers: {}, + body: "We only accept GET /" + }; + } catch(error) { + var body = error.stack || JSON.stringify(error, null, 2); + return { + statusCode: 400, + headers: {}, + body: JSON.stringify(body) + } + } + } + +Save it and make sure it builds and creates an empty stack. +Note that since we haven't wired the function to our app, +the Lambda file does not appear in the output. + +.. code-block:: sh + + npm run build + cdk synth + +.. _create_widgets_service: + +Step 3: Create Widgets Service +============================== + +Add the |ABP|, |LAM|, and |S3| packages to our app. + +.. code-block:: sh + + npm install @aws-cdk/aws-apigateway @aws-cdk/aws-lambda @aws-cdk/aws-s3 + +Create the directory *lib* at the same level as the *bin* and *resources* +directories. + +.. code-block:: sh + + mkdir lib + +Create the following Typescript file, *widget_service.ts*, +in the *lib* directory. + +.. code-block:: ts + + import cdk = require('@aws-cdk/cdk'); + import apigateway = require('@aws-cdk/aws-apigateway'); + import lambda = require('@aws-cdk/aws-lambda'); + import s3 = require('@aws-cdk/aws-s3'); + + export class WidgetService extends cdk.Construct { + constructor(parent: cdk.Construct, name: string) { + super(parent, name); + + // Use S3 bucket to store our widgets + const bucket = new s3.Bucket(this, 'WidgetStore'); + + // Create a handler that calls the function main + // in the source file widgets(.js) in the resources directory + // to handle requests through API Gateway + const handler = new lambda.Function(this, 'WidgetHandler', { + runtime: lambda.Runtime.NodeJS810, + code: lambda.Code.directory('resources'), + handler: 'widgets.main', + environment: { + BUCKET: bucket.bucketName // So runtime has the bucket name + } + }); + + bucket.grantReadWrite(handler.role); + + // Create an API Gateway REST API + const api = new apigateway.RestApi(this, 'widgets-api', { + restApiName: 'Widget Service', + description: 'This service serves widgets.' + }); + + // Pass the request to the handler + const getWidgetsIntegration = new apigateway.LambdaIntegration(handler); + + // Use the getWidgetsIntegration when there is a GET request + api.root.addMethod('GET', getWidgetsIntegration); // GET / + } + } + +Save it and make sure it builds and creates a (still empty) stack. + +.. code-block:: sh + + npm run build + cdk synth + +.. _add_service: + +Step 4: Add the Service to the App +================================== + +To add the service to our app, +add the following line of code after the existing **import** statement in +*my_widget_service.ts*. + +.. code-block:: ts + + import widget_service = require('../lib/widget_service'); + +Add the following line of code at the end of the constructor in *my_widget_service.ts*. + +.. code-block:: ts + + new widget_service.WidgetService(this, 'Widgets'); + +Make sure it builds and creates a stack +(we don't show the stack as it's almost 300 lines). + +.. code-block:: sh + + npm run build + cdk synth + +.. _deploy_and_test: + +Step 5: Deploy and Test the App +=============================== + +Before you can deploy your first |cdk| app, +you must bootstrap your deployment, +which creates some AWS infracture that the |cdk| +needs. +See the **bootstrap** section of the :doc:`tools` topic for details. + +.. code-block:: sh + + cdk bootstrap + +Run the following command to deploy your app. + +.. code-block:: sh + + cdk deploy + +If the deployment is successfull, +save the URL for your server, which appears in the last line in the window, +where GUID is an alpha-numeric GUID and REGION is your region. + +.. code-block:: sh + + https://GUID.execute-REGION.amazonaws.com/prod/ + +You can test your app by getting the list of widgets (currently empty) by navigating to this URL in a +browser or use the following **curl** command. + +.. code-block:: sh + + curl -X GET 'https://GUID.execute-REGION.amazonaws.com/prod' + +You can also open the |console|, +navigate to the |ABP| service, +find **Widget Service** in the list. +Select **GET** and **Test** to test the function. +Since we haven't stored any widgets yet, the output should be similar to the following +(there may be some slight differences in whitespace and quotation marks). + +.. code-block:: sh + + { "widgets": [] } + +.. _adding_functions: + +Step 6: Add the Individual Widget Functions +=========================================== + +The next step is to create |LAM| functions to create, show, and delete +individual widgets. +Replace the existing **exports.main** function in *widgets.js* with the following code. + +.. code-block:: js + + exports.main = async function(event, context) { + try { + var method = event.httpMethod; + // Get name, if present + var widgetName = event.path.startsWith('/') ? event.path.substring(1) : event.path; + + if (method === "GET") { + // GET / to get the names of all widgets + if (event.path === "/") { + const data = await S3.listObjectsV2({ Bucket: bucketName }).promise(); + var body = { + widgets: data.Contents.map(function(e) { return e.Key }) + }; + return { + statusCode: 200, + headers: {}, + body: JSON.stringify(body) + }; + } + + if (widgetName) { + // GET /name to get info on widget name + const data = await S3.getObject({ Bucket: bucketName, Key: widgetName}).promise(); + var body = data.Body.toString('utf-8'); + + return { + statusCode: 200, + headers: {}, + body: JSON.stringify(body) + }; + } + } + + if (method === "POST") { + // POST /name + // Return error if we do not have a name + if (!widgetName) { + return { + statusCode: 400, + headers: {}, + body: "Widget name missing" + }; + } + + // Create some dummy data to populate object + const now = new Date(); + var data = widgetName + " created: " + now; + + var base64data = new Buffer(data, 'binary'); + + await S3.putObject({ + Bucket: bucketName, + Key: widgetName, + Body: base64data, + ContentType: 'application/json' + }).promise(); + + return { + statusCode: 200, + headers: {}, + body: JSON.stringify(event.widgets) + }; + } + + if (method === "DELETE") { + // DELETE /name + // Return an error if we do not have a name + if (!widgetName) { + return { + statusCode: 400, + headers: {}, + body: "Widget name missing" + }; + } + + await S3.deleteObject({ + Bucket: bucketName, Key: widgetName + }).promise(); + + return { + statusCode: 200, + headers: {}, + body: "Successfully deleted widget " + widgetName + }; + } + + // We got something besides a GET, POST, or DELETE + return { + statusCode: 400, + headers: {}, + body: "We only accept GET, POST, and DELETE, not " + method + }; + } catch(error) { + var body = error.stack || JSON.stringify(error, null, 2); + return { + statusCode: 400, + headers: {}, + body: body + } + } + } + +Wire these functions up to our |ABP| code in *widget_service.ts* +by adding the following code at the end of the constructor. + +.. code-block:: ts + + const widget = api.root.addResource('{name}'); + + // Add new widget to bucket with: POST /{name} + const postWidgetIntegration = new apigateway.LambdaIntegration(handler); + + // Get a specific widget from bucket with: GET /{name} + const getWidgetIntegration = new apigateway.LambdaIntegration(handler); + + // Remove a specific widget from the bucket with: DELETE /{name} + const deleteWidgetIntegration = new apigateway.LambdaIntegration(handler); + + widget.addMethod('POST', postWidgetIntegration); // POST /{name} + widget.addMethod('GET', getWidgetIntegration); // GET /{name} + widget.addMethod('DELETE', deleteWidgetIntegration); // DELETE /{name} + +Save, build, and deploy the app. + +Now we should be able to store, show, or delete an individual widget. +Use the following **curl** commands to list the widgets, +create the widget *dummy*, +list all of the widgets, +show the contents of *dummy* (it should show today's date), +and delete *dummy*, +and again show the list of widgets. + +.. code-block:: sh + + curl -X GET 'https://GUID.execute-REGION.amazonaws.com/prod' + curl -X POST 'https://GUID.execute-REGION.amazonaws.com/prod/dummy' + curl -X GET 'https://GUID.execute-REGION.amazonaws.com/prod' + curl -X GET 'https://GUID.execute-REGION.amazonaws.com/prod/dummy' + curl -X DELETE 'https://GUID.execute-REGION.amazonaws.com/prod/dummy' + curl -X GET 'https://GUID.execute-REGION.amazonaws.com/prod' + +You can also use the |ABP| console to test these functions. +You'll have to set the **name** entry to the name of an widget, +such as **dummy**. diff --git a/docs/src/ecs_example.rst b/docs/src/ecs_example.rst new file mode 100644 index 0000000000000..4269ac53ab6fa --- /dev/null +++ b/docs/src/ecs_example.rst @@ -0,0 +1,218 @@ +.. 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. + +.. _cdk_examples: + +############## +|cdk| Examples +############## + +This topic contains some usage examples to help you get started understanding +the |cdk|. + +.. We'll include this if we ever implement DeploymentPipeline + _multiple_stacks_example: + + Creating an App with Multiple Stacks + ==================================== + + The following example creates the following stacks and one deployment pipeline: + + - **Dev** uses the default environment + - **PreProd** in the **us-west-2** Region + - **NAEast** in the **us-east-1** Region + - **NAWest** in the **us-west-2** Region + - **EU** in the **eu-west-1** Region + - **DeploymentPipeline** in the **us-east-1** Region + + Implement the class **MyStack** in the *my-stack* sub-folder, + that extends the |stack-class| class + (this is the same code as shown in the :doc:`concepts` topic). + + code-block:: js + + import { Stack, StackProps } from '@aws-cdk/cdk' + + interface MyStackProps extends StackProps { + encryptedStorage: boolean; + } + + export class MyStack extends Stack { + constructor(parent: Construct, name: string, props?: MyStackProps) { + super(parent, name, props); + + new MyStorageLayer(this, 'Storage', { encryptedStorage: props.encryptedStorage }); + new MyControlPlane(this, 'CPlane'); + new MyDataPlane(this, 'DPlane'); + } + } + + Implement the class **DeploymentPipeline** in the *my-deployment* sub-folder, + that extends the |stack-class| class + (this is the same code as shown in the :doc:`concepts` topic). + + code-block:: js + + Use **MyStack** and **DeploymentPipeline** to create the stacks and deployment pipeline. + + code-block:: js + + import { App } from '@aws-cdk/cdk' + import { MyStack } from './my-stack' + import { DeploymentPipeline } from './my-deployment' + + const app = new App(); + + // Use the default environment + new MyStack(app, { name: 'Dev' }); + + // Pre-production stack + const preProd = new MyStack(app, { + name: 'PreProd', + env: { region: 'us-west-2' }, + preProd: true + }); + + // Production stacks + const prod = [ + new MyStack(app, { + name: 'NAEast', + env: { region: 'us-east-1' } + }), + + new MyStack(app, { + name: 'NAWest', + env: { region: 'us-west-2' } + }), + + new MyStack(app, { + name: 'EU', + env: { region: 'eu-west-1' }, + encryptedStorage: true + }) + ] + + // CI/CD pipeline stack + new DeploymentPipeline(app, { + env: { region: 'us-east-1' }, + strategy: DeploymentStrategy.Waved, + preProdStages: [ preProd ], + prodStages: prod + }); + + app.run(); + +.. _dynamodb_example: + +Creating a |DDB| Table +====================== + +The following example creates a +|DDB| table with the partition key **Alias** +and sort key **Timestamp**. + +.. code-block:: js + + import dynamodb = require('@aws-cdk/aws-dynamodb'); + import cdk = require('@aws-cdk/cdk'); + + class MyStack extends cdk.Stack { + constructor(parent: cdk.App, name: string, props?: cdk.StackProps) { + super(parent, name, props); + + const table = new dynamodb.Table(this, 'Table', { + tableName: 'MyAppTable', + readCapacity: 5, + writeCapacity: 5 + }); + + table.addPartitionKey({ name: 'Alias', type: dynamodb.AttributeType.String }); + table.addSortKey({ name: 'Timestamp', type: dynamodb.AttributeType.String }); + } + } + + const app = new cdk.App(); + + new MyStack(app, 'MyStack'); + + app.run(); + +.. _creating_rds_example: + +Creating an |RDS| Database +========================== + +The following example creates the Aurora database **MyAuroraDatabase**. + +.. code-block:: js + + import ec2 = require('@aws-cdk/aws-ec2'); + import rds = require('@aws-cdk/aws-rds'); + import cdk = require('@aws-cdk/cdk'); + + class MyStack extends cdk.Stack { + constructor(parent: cdk.App, name: string, props?: cdk.StackProps) { + super(parent, name, props); + + const vpc = new ec2.VpcNetwork(this, 'VPC'); + + new rds.DatabaseCluster(this, 'MyRdsDb', { + defaultDatabaseName: 'MyAuroraDatabase', + masterUser: { + username: 'admin', + password: '123456' + }, + engine: rds.DatabaseClusterEngine.Aurora, + instanceProps: { + instanceType: new ec2.InstanceTypePair(ec2.InstanceClass.Burstable2, ec2.InstanceSize.Small), + vpc: vpc, + vpcPlacement: { + subnetsToUse: ec2.SubnetType.Public + } + } + }); + } + } + + const app = new cdk.App(); + + new MyStack(app, 'MyStack'); + + app.run(); + +.. _creating_s3_example: + +Creating an |S3| Bucket +======================= + +The following example creates the |S3| bucket **MyS3Bucket** with server-side KMS +encryption provided by |S3|. + +.. code-block:: js + + import s3 = require('@aws-cdk/aws-s3'); + import cdk = require('@aws-cdk/cdk'); + + class MyStack extends cdk.Stack { + constructor(parent: cdk.App, name: string, props?: cdk.StackProps) { + super(parent, name, props); + + new s3.Bucket(this, 'MyBucket', { + bucketName: 'MyS3Bucket', + encryption: s3.BucketEncryption.KmsManaged + }); + } + } + + const app = new cdk.App(); + + new MyStack(app, 'MyStack'); + + app.run() diff --git a/docs/src/getting-started.rst b/docs/src/getting-started.rst index f4974f65838a4..e316be102030b 100644 --- a/docs/src/getting-started.rst +++ b/docs/src/getting-started.rst @@ -10,18 +10,21 @@ .. _getting_started: -##################################### -Creating Your First |cdk| Application -##################################### +############################## +Getting Started with the |cdk| +############################## -This topic walks you through creating and deploying your first |cdk| app. +This topic describes how to download, install, and configure the |cdk|. -.. _setup: +.. _installing_cdk: -Setting up the |cdk| +Installing the |cdk| ==================== -.. _setup_prerequisites: +This section describes how to install the |cdk|, +and lists the prerequsites for each supported language. + +.. _installing_prerequisites: Prerequisites ------------- @@ -39,7 +42,7 @@ You must specify both your credentials and a region to use the toolkit. See :ref:`credentials ` for information on using the AWS CLI to specify your credentials. -.. _setup_install: +.. _installing_toolkit: Installing the Command-Line Toolkit ----------------------------------- @@ -57,342 +60,25 @@ Run the following command to see the currently installed version of the toolkit cdk --version -.. _initializing: - -Initializing the Project -======================== - -.. note:: - - This guide walks you through the process of creating an |cdk| project. - You can also use the - :code:`cdk init` command to create a skeleton project from a - template in any of the supported languages. - -Create an empty project structure for the |cdk| app. - -.. The cdk init -l typescript version of package.json also includes - a "cdk": "cdk" - entry in "scripts" - -.. tabs:: - - .. group-tab:: C# - - Create a new empty, source controlled directory and then create a new - console application. - - .. code-block:: sh - - mkdir HelloCdk - cd HelloCdk - dotnet new console - - .. group-tab:: JavaScript - - 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 **.gitignore** file with the following content: - - .. code-block:: sh - - *.js - node_modules - - .. 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 **.gitignore** file with the following content: - - .. code-block:: sh - - *.js - *.d.ts - node_modules - - Add the `build` and `watch` TypeScript commands to **package.json**: - - .. code-block:: json - - { - "scripts": { - "build": "tsc", - "watch": "tsc -w" - } - } - - Create a minimal **tsconfig.json**: - - .. code-block:: json - - { - "compilerOptions": { - "target": "es2018", - "module": "commonjs" - } - } - - .. group-tab:: Java - - Create an empty source-controlled directory for your project: - - .. code-block:: sh - - mkdir hello-cdk - cd hello-cdk - git init - - Create a **.gitignore** file with the following content: - - .. code-block:: sh - - .classpath.txt - target - .classpath - .project - .idea - .settings - .vscode - *.iml - - 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_core: - -Adding @aws-cdk/cdk as a Dependency -=================================== - -Install the |cdk| core library (:py:mod:`@aws-cdk/cdk`). This -library includes the basic classes needed to write |cdk| stacks and apps. - -.. tabs:: - - .. group-tab:: C# - - Install the **Amazon.CDK NuGet** package: - - .. code-block:: sh - - dotnet add package Amazon.CDK - - .. group-tab:: JavaScript - - Install the **@aws-cdk/cdk** package: - - .. code-block:: sh - - npm install @aws-cdk/cdk - - .. group-tab:: TypeScript - - Install the **@aws-cdk/cdk** package: - - .. code-block:: sh - - npm install @aws-cdk/cdk - - .. group-tab:: Java - - Add the following to your project's `pom.xml` file: - - .. code-block:: xml - - - - software.amazon.awscdk - cdk - - - - -.. _define_app: - -Defining the |cdk| App -====================== - -|cdk| apps are classes that extend the :py:class:`App <@aws-cdk/cdk.App>` -class. Create an empty **App**: - -.. tabs:: - - .. group-tab:: C# - - In **Program.cs** - - .. code-block:: c# - - using Amazon.CDK; - - namespace HelloCdk - { - class Program - { - static void Main(string[] args) - { - var myApp = new App(); - myApp.Run(); - } - } - } - - .. group-tab:: JavaScript +.. _configuring_cdk: - Create the file **bin/hello-cdk.js**: - - .. code-block:: js - - const cdk = require('@aws-cdk/cdk'); - - class MyApp extends cdk.App { - constructor() { - super(); - } - } - - new MyApp().run(); - - .. group-tab:: TypeScript - - Create the file **bin/hello-cdk.ts**: - - .. code-block:: ts - - import cdk = require('@aws-cdk/cdk'); - - class MyApp extends cdk.App { - constructor() { - super(); - } - } - - new MyApp().run(); - - .. group-tab:: Java - - In **src/main/java/com/acme/MyApp.java**: - - .. code-block:: java - - package com.acme; - - import software.amazon.awscdk.App; - - import java.util.Arrays; - - public class MyApp { - public static void main(final String argv[]) { - App app = new App(); - - app.run(); - } - } - -.. _complie_code: - -Compiling the Code -================== - -If needed, compile the code: - -.. tabs:: - - .. group-tab:: C# - - Compile the code using your IDE or via the dotnet CLI: - - .. code-block:: sh - - dotnet build - - .. 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 - - Compile your code using your IDE or via the command line via **mvn**: - - .. code-block:: sh - - mvn compile - -You have now created your first |cdk| app. - -.. _credentials: - -Configuring the |cdk| Toolkit -============================= - -Use the |cdk| toolkit to view the contents of an app. - -.. note:: +Configuring the |cdk| +===================== - You must specify your default credentials and region to use the toolkit. +You must specify your default credentials and region to use the toolkit. - Use the `AWS Command Line Interface `_ - ``aws configure`` command to specify your default credentials and region. +Use the `AWS Command Line Interface `_ +``aws configure`` command to specify your default credentials and 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. +You can also set environment variables for your default credentials and region. +Environment variables take precedence over settings in the credentials or config file. - * *AWS_ACCESS_KEY_ID* specifies your access key - * *AWS_SECRET_ACCESS_KEY* specifies your secret access key - * *AWS_DEFAULT_REGION* specifies your default region +* *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. +See `Environment Variables `_ +in the CLI User Guide for details. .. include:: region-note.rst @@ -495,604 +181,3 @@ your project directory with the following content: "app": "/bin/bash ./app.sh" } -.. _list_stacks: - -List the Stacks in the App -========================== - -Use the |cdk| toolkit's **ls** command to list the stacks in the app. - -.. code-block:: sh - - cdk ls -l - -The result is an empty array: - -.. code-block:: sh - - [] - -An empty array makes sense, since our app doesn't have any stacks. - -.. note:: - - There is a known issue on Windows with the |cdk| .NET environment. - Whenever you use a **cdk** command, - it issues a node warning similar to the following: - - .. code-block:: sh - - (node:27508) UnhandledPromiseRejectionWarning: Unhandled promise rejection - (rejection id: 1): Error: EPIPE: broken pipe, write - (node:27508) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. - In the future, promise rejections that are not handled will terminate the - Node.js process with a non-zero exit code. - - You can safely ignore this warning. - -.. _define_stack: - -Define a Stack -============== - -Define a stack and add it to the app. - -.. tabs:: - - .. group-tab:: C# - - Create **MyStack.cs**: - - .. code-block:: c# - - using Amazon.CDK; - - namespace HelloCdk - { - public class MyStack: Stack - { - public MyStack(App parent, string name) : base(parent, name, null) - { - } - } - } - - In **Program.cs**: - - .. code-block:: c# - :emphasize-lines: 10 - - using Amazon.CDK; - - namespace HelloCdk - { - class Program - { - static void Main(string[] args) - { - var myApp = new App(); - new MyStack(myApp, "hello-cdk"); - myApp.Run(); - } - } - } - - .. group-tab:: JavaScript - - In **index.js**: - - .. code-block:: js - :emphasize-lines: 3,4,5,6,7,13 - - const cdk = require('@aws-cdk/cdk'); - - class MyStack extends cdk.Stack { - constructor(parent, id, props) { - super(parent, id, props); - } - } - - class MyApp extends cdk.App { - constructor(argv) { - super(argv); - - new MyStack(this, 'hello-cdk'); - } - } - - new MyApp().run(); - - .. group-tab:: TypeScript - - In **index.ts**: - - .. code-block:: ts - :emphasize-lines: 3,4,5,6,7,13 - - import cdk = require('@aws-cdk/cdk'); - - class MyStack extends cdk.Stack { - constructor(parent: cdk.App, id: string, props?: cdk.StackProps) { - super(parent, id, props); - } - } - - class MyApp extends cdk.App { - constructor() { - super(); - new MyStack(this, 'hello-cdk'); - } - } - - new MyApp().run(); - - .. group-tab:: Java - - In **src/main/java/com/acme/MyStack.java**: - - .. code-block:: java - - package com.acme; - - import software.amazon.awscdk.App; - import software.amazon.awscdk.Stack; - import software.amazon.awscdk.StackProps; - - public class MyStack extends Stack { - public MyStack(final App parent, final String name) { - this(parent, name, null); - } - - public MyStack(final App parent, final String name, final StackProps props) { - super(parent, name, props); - } - } - - In **src/main/java/com/acme/MyApp.java**: - - .. code-block:: java - :emphasize-lines: 12 - - package com.acme; - - import software.amazon.awscdk.App; - import java.util.Arrays; - - public class MyApp { - public static void main(final String argv[]) { - App app = new App(); - - new MyStack(app, "hello-cdk"); - - app.run(); - } - } - -The initializer signature of **cdk.Stack** includes the 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 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 :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. - -Compile your program: - -.. tabs:: - - .. group-tab:: C# - - We have configured cdk.json to run "dotnet run", which will - restore dependencies, build, and run your application. - Therefore, you just need to run the CDK command. - - .. group-tab:: JavaScript - - Nothing to compile. - - .. group-tab:: TypeScript - - .. code-block:: sh - - npm run build - - .. group-tab:: Java - - .. code-block:: sh - - mvn compile - -Run **cdk ls** to see that the app includes a single -stack: - -.. code-block:: sh - - cdk ls -l - - - 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. See :doc:`environments` for more -details on how to associate stacks to environments. - -.. _define_bucket: - -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. - -Install the **@aws-cdk/aws-s3** package: - -.. tabs:: - - .. group-tab:: C# - - .. code-block:: sh - - dotnet add package Amazon.CDK.AWS.S3 - - .. group-tab:: JavaScript - - .. code-block:: sh - - npm install @aws-cdk/aws-s3 - - .. group-tab:: TypeScript - - .. code-block:: sh - - npm install @aws-cdk/aws-s3 - - .. group-tab:: Java - - Edit your **pom.xml** file: - - .. code-block:: sh - - - software.amazon.awscdk - s3 - - - -Next, define an |S3| bucket in the stack. |S3| buckets are represented by -the :py:class:`Bucket <@aws-cdk/aws-s3.Bucket>` class: - -.. tabs:: - - .. group-tab:: C# - - Create **MyStack.cs**: - - .. code-block:: c# - :emphasize-lines: 2,10,11,12,13 - - using Amazon.CDK; - using Amazon.CDK.AWS.S3; - - namespace HelloCdk - { - public class MyStack : Stack - { - public MyStack(App parent, string name) : base(parent, name, null) - { - new Bucket(this, "MyFirstBucket", new BucketProps - { - Versioned = true - }); - } - } - } - - .. group-tab:: JavaScript - - In **index.js**: - - .. code-block:: js - :emphasize-lines: 2,8,9,10 - - const cdk = require('@aws-cdk/cdk'); - const s3 = require('@aws-cdk/aws-s3'); - - class MyStack extends cdk.Stack { - constructor(parent, id, props) { - super(parent, id, props); - - new s3.Bucket(this, 'MyFirstBucket', { - versioned: true - }); - } - } - - .. group-tab:: TypeScript - - In **index.ts**: - - .. code-block:: ts - :emphasize-lines: 2,8,9,10 - - import cdk = require('@aws-cdk/cdk'); - import s3 = require('@aws-cdk/aws-s3'); - - class MyStack extends cdk.Stack { - constructor(parent: cdk.App, id: string, props?: cdk.StackProps) { - super(parent, id, props); - - new s3.Bucket(this, 'MyFirstBucket', { - versioned: true - }); - } - } - - .. group-tab:: Java - - In **src/main/java/com/acme/MyStack.java**: - - .. code-block:: java - :emphasize-lines: 6,7,13,14,15 - - package com.acme; - - import software.amazon.awscdk.App; - import software.amazon.awscdk.Stack; - import software.amazon.awscdk.StackProps; - import software.amazon.awscdk.services.s3.Bucket; - import software.amazon.awscdk.services.s3.BucketProps; - - public class MyStack extends Stack { - public MyStack(final App parent, final String name) { - this(parent, name, null); - } - - public MyStack(final App parent, final String name, final StackProps props) { - super(parent, name, props); - - new Bucket(this, "MyFirstBucket", BucketProps.builder() - .withVersioned(true) - .build()); - } - } - -A few things to notice: - -* :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: - -.. tabs:: - - .. group-tab:: C# - - We have configured cdk.json to run "dotnet run", which will - restore dependencies, build, and run your application. - Therefore, you just need to run the CDK command. - - .. group-tab:: JavaScript - - Nothing to compile. - - .. group-tab:: TypeScript - - .. code-block:: sh - - npm run build - - .. group-tab:: Java - - .. code-block:: sh - - mvn compile - -.. _synthesize_template: - -Synthesize an |CFN| Template -============================ - -Synthesize a |cfn| template for the stack: - -.. code-block:: sh - - cdk synth hello-cdk - -.. note:: Since the |cdk| app only contains a single stack, you can omit :code:`hello-cdk`. - -This command executes the |cdk| app and synthesize an |CFN| template for the -**hello-cdk** stack: - -.. code-block:: yaml - - Resources: - MyFirstBucketB8884501: - Type: 'AWS::S3::Bucket' - 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 -=================== - -Use **cdk deploy** to deploy the stack: - -.. code-block:: sh - - 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 -account. The command displays information as it progresses. - -.. _modify_cde: - -Modifying the Code -================== - -Configure the bucket to use KMS managed encryption: - -.. tabs:: - - .. group-tab:: C# - - .. code-block:: c# - :emphasize-lines: 4 - - new Bucket(this, "MyFirstBucket", new BucketProps - { - Versioned = true, - Encryption = BucketEncryption.KmsManaged - }); - - .. group-tab:: JavaScript - - .. code-block:: js - :emphasize-lines: 3 - - new s3.Bucket(this, 'MyFirstBucket', { - versioned: true, - encryption: s3.BucketEncryption.KmsManaged - }); - - .. group-tab:: TypeScript - - .. code-block:: ts - :emphasize-lines: 3 - - new s3.Bucket(this, 'MyFirstBucket', { - versioned: true, - encryption: s3.BucketEncryption.KmsManaged - }); - - .. group-tab:: Java - - .. code-block:: java - :emphasize-lines: 3 - - new Bucket(this, "MyFirstBucket", BucketProps.builder() - .withVersioned(true) - .withEncryption(BucketEncryption.KmsManaged) - .build()); - -Compile the program: - -.. tabs:: - - .. group-tab:: C# - - We have configured cdk.json to run "dotnet run", which will - restore dependencies, build, and run your application. - Therefore, you just need to run the CDK command. - - .. group-tab:: JavaScript - - Nothing to compile. - - .. group-tab:: TypeScript - - .. code-block:: sh - - npm run build - - .. group-tab:: Java - - .. code-block:: sh - - mvn compile - -.. _prepare_deployment: - -Preparing for Deployment -======================== - -Before you deploy the updated stack, use the ``cdk diff`` command to evaluate -the difference between the |cdk| app and the deployed stack: - -.. code-block:: sh - - 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. -The output should look like the following: - -.. code-block:: sh - - [~] 🛠 Updating MyFirstBucketB8884501 (type: AWS::S3::Bucket) - └─ [+] .BucketEncryption: - └─ New value: {"ServerSideEncryptionConfiguration":[{"ServerSideEncryptionByDefault":{"SSEAlgorithm":"aws:kms"}}]} - -As you can see, the diff indicates that the -**ServerSideEncryptionConfiguration** property of the bucket is now set to -enable server-side encryption. - -You can also see that the bucket is not going to be replaced but rather updated -("**Updating MyFirstBucketB8884501**"). - -Run **cdk deploy** to update the stack: - -.. code-block:: sh - - cdk deploy - -The toolkit updates the bucket configuration to enable server-side KMS -encryption for the bucket: - -.. code-block:: sh - - ⏳ 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 - -.. _whats_next: - -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/docs/src/index.rst b/docs/src/index.rst index facc8ca48aa67..109981a62d3cf 100644 --- a/docs/src/index.rst +++ b/docs/src/index.rst @@ -22,6 +22,19 @@ To get started see :doc:`getting-started` .. image:: screencast.gif +.. npm install -g aws-cdk + ADDED: mkdir ~/hello-cdk; cd ~/hello-cdk + cdk init --language typescript + npm run build + ADDED: cdk synth + cdk deploy + ADDED: + vim bin/aws-cdk.ts -> lib/hello-cdk-stack.ts + // add SNS, SQS, queue, topic, topic.subscribeQueue + cdk diff + cdk deploy + cdk diff + Developers can use one of the supported programming languages to define reusable cloud components called :doc:`constructs`, which are composed together into :doc:`stacks` and :doc:`apps`. @@ -63,10 +76,11 @@ In addition to this guide, the following are other resources available to |cdk| * `Stack Overflow `_ * `GitHub repository `_ + * `License `_ + * `Issues `_ + * `Releases `_ * `Examples `_ * `Documentation source `_ - * `Issues `_ - * `License `_ * `AWS CDK Sample for Cloud9 `_ * `AWS CloudFormation Concepts `_ @@ -94,10 +108,10 @@ To obtain an AWS account, go to `aws.amazon.com `_ and c Getting Started Tutorial + Examples Concepts AWS Construct Library AWS CloudFormation Library - Examples Tools Writing Constructs Reference diff --git a/docs/src/region-note.rst b/docs/src/region-note.rst index a69e31af4170f..9dc7e361dc061 100644 --- a/docs/src/region-note.rst +++ b/docs/src/region-note.rst @@ -12,5 +12,5 @@ The China regions (cn-north-1 and cn-northwest-1) do not support version reporting. - See :ref:`version-reporting` for more details and how to - :ref:`opt-out ` + See :ref:`version_reporting` for more details and how to + :ref:`opt-out ` diff --git a/docs/src/tools.rst b/docs/src/tools.rst index 77c60c257b349..fd1216f3ef683 100644 --- a/docs/src/tools.rst +++ b/docs/src/tools.rst @@ -96,7 +96,7 @@ Here 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. -.. _version-reporting: +.. _version_reporting: Version Reporting ================= @@ -118,7 +118,7 @@ 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" -.. _version-reporting-opt-out: +.. _version_reporting_opt_out: Opting-out from Version Reporting --------------------------------- diff --git a/docs/src/tutorial.rst b/docs/src/tutorial.rst index ef2be74938b61..115b7332d80aa 100644 --- a/docs/src/tutorial.rst +++ b/docs/src/tutorial.rst @@ -10,456 +10,978 @@ .. _tutorial: -############## -|cdk| Tutorial -############## +###################################### +Tutorial: Creating a |cdk| Application +###################################### -This topic steps you through creating the resources for a simple widget dispensing -service using the |cdk|. +This topic walks you through creating and deploying a |cdk| app, +by using the `cdk init` command, as described in `Creating a Project from the Template`_, +or manually, as described in `Manually Creating a Project`_. -.. _overview: +In either case, the first step is to create the directory for your project, +with an empty Git repository. +All of these instructions use this directory: -Overview -======== +.. code-block:: sh -This tutorial contains the following steps. + mkdir hello-cdk + cd hello-cdk + git init -1. Create a |cdk| app +.. _cdk_init_project: -2. Create a |LAMlong| function that gets a list of widgets with: GET / +Creating a Project from the Template +==================================== -3. Create the service that calls the |LAM| function +As mentioned previously, +you can use the :code:`cdk init` command to create a skeleton project from a +template in any of the supported languages. +In this section we'll do just that. -4. Add the service to the |cdk| app +.. _initialize: -5. Test the app +Initializing the Project +------------------------ -6. Add |LAM| functions to: +Run the `cdk init` command to initialize an empty project. +The |cdk| contains templates for all of the supported languages. +To create an empty (no AWS resources in the resulting |CFN| stack), +run the following command, where LANGUAGE is one of the supported programming languages: +**csharp** (C#), **java** (Java), or **typescript** (TypeScript). - * create an widget based with: POST /{name} - * get an widget by name with: GET /{name} - * delete an widget by name with: DELETE /{name} +.. code-block:: sh -.. _create_app: + cdk init --language LANGUAGE -Step 1: Create a |cdk| App -========================== +.. _compile_project: -Let's create the TypeScript app **MyWidgetService** in in the current folder. +Compiling the Project +--------------------- -.. code-block:: sh +If needed, compile the code: - mkdir MyWidgetService - cd MyWidgetService - cdk init --language typescript +.. tabs:: -This creates *my_widget_service.ts* in the *bin* directory. -We don't need most of this code, -so for now change it to the following: + .. group-tab:: C# -.. code-block:: ts + Compile the code using your IDE or via the dotnet CLI: - #!/usr/bin/env node - import cdk = require('@aws-cdk/cdk'); + .. code-block:: sh - class MyWidgetServiceStack extends cdk.Stack { - constructor(parent: cdk.App, name: string, props?: cdk.StackProps) { - super(parent, name, props); + dotnet build + .. group-tab:: JavaScript - } - } + No need to compile - // Create a new CDK app - const app = new cdk.App(); + .. group-tab:: TypeScript - // Add your stack to it - new MyWidgetServiceStack(app, 'MyWidgetServiceStack'); + To compile your program from **.ts** to **.js**: - app.run(); + .. code-block:: sh -Save it and make sure it builds and creates an empty stack. + npm run build -.. code-block:: sh + 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: - npm run build - cdk synth + .. code-block:: sh -You should see a stack like the following, -where CDK-VERSION is the version of the CDK. + # run in another terminal session + npm run watch -.. code-block:: sh + .. group-tab:: Java - Resources: - CDKMetadata: - Type: 'AWS::CDK::Metadata' - Properties: - Modules: >- - @aws-cdk/cdk=CDK-VERSION,@aws-cdk/cx-api=CDK-VERSION,my_widget_service=0.1.0 + Compile your code using your IDE or via the command line via **mvn**: -.. _create_lambda_functions: + .. code-block:: sh -Step 2: Create a |LAM| Function to List all Widgets -=================================================== + mvn compile -The next step is to create a |LAM| function to list all of the widgets in our -|S3| bucket. +You have now created your first |cdk| app. +Since the next section manually creates the same, empty project, +you can skip forward to `Listing the Stacks in the App`_. -Create the directory *resources* at the same level as the *bin* directory. +.. _manual_project: -.. code-block:: sh +Manually Creating a Project +=========================== - mkdir resources - -Create the following Javascript file, *widgets.js*, -in the *resources* directory. - -.. code-block:: js - - const AWS = require('aws-sdk'); - const S3 = new AWS.S3(); - - const bucketName = process.env.BUCKET; - - exports.main = async function(event, context) { - try { - var method = event.httpMethod; - - if (method === "GET") { - if (event.path === "/") { - const data = await S3.listObjectsV2({ Bucket: bucketName }).promise(); - var body = { - widgets: data.Contents.map(function(e) { return e.Key }) - }; - return { - statusCode: 200, - headers: {}, - body: JSON.stringify(body) - }; - } - } - - // We only accept GET for now - return { - statusCode: 400, - headers: {}, - body: "We only accept GET /" - }; - } catch(error) { - var body = error.stack || JSON.stringify(error, null, 2); - return { - statusCode: 400, - headers: {}, - body: JSON.stringify(body) - } - } - } - -Save it and make sure it builds and creates an empty stack. -Note that since we haven't wired the function to our app, -the Lambda file does not appear in the output. +In this section we create a new |cdk| project using explicit command-line commands. +Be sure to navigate to the *hello-cdk* directory before you start. -.. code-block:: sh +.. _initializing_manually: + +Initializing the Project +------------------------ + +Create an empty project for the |cdk| app. + +.. tabs:: + + .. group-tab:: C# + + Create a new console application. + + .. code-block:: sh + + dotnet new console + + .. group-tab:: JavaScript + + Create an initial npm **package.json** file: + + .. code-block:: sh + + npm init -y # creates package.json + + Create a **.gitignore** file with the following content: + + .. code-block:: sh + + *.js + node_modules + + .. group-tab:: TypeScript + + Create an initial npm **package.json** file: + + .. code-block:: sh + + npm init -y # creates package.json + + Create a **.gitignore** file with the following content: + + .. code-block:: sh + + *.js + *.d.ts + node_modules + + Add the `build` and `watch` TypeScript commands to **package.json**: + + .. code-block:: json + + { + "scripts": { + "build": "tsc", + "watch": "tsc -w" + } + } + + Create a minimal **tsconfig.json**: + + .. code-block:: json + + { + "compilerOptions": { + "target": "es2018", + "module": "commonjs" + } + } + + Create a minimal **cdk.json** (this saves you from including `--app node bin/hello-cdk.js` in every `cdk` command): + + .. code-block:: json + + { + "app": "node bin/hello-cdk.js" + } + + .. group-tab:: Java + + Create a **.gitignore** file with the following content: + + .. code-block:: sh + + .classpath.txt + target + .classpath + .project + .idea + .settings + .vscode + *.iml + + 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_core: + +Adding the CDK Core as a Dependency +----------------------------------- + +Install the |cdk| core library (:py:mod:`@aws-cdk/cdk`) +This library includes the basic classes needed to write |cdk| stacks and apps. + +.. tabs:: + + .. group-tab:: C# + + Install the **Amazon.CDK NuGet** package: + + .. code-block:: sh + + dotnet add package Amazon.CDK + + .. group-tab:: JavaScript + + Install the **@aws-cdk/cdk** package: + + .. code-block:: sh + + npm install @aws-cdk/cdk + + .. group-tab:: TypeScript + + Install the **@aws-cdk/cdk** package: + + .. code-block:: sh + + npm install @aws-cdk/cdk + + .. group-tab:: Java + + Add the following to your project's `pom.xml` file: + + .. code-block:: xml + + + + software.amazon.awscdk + cdk + + + - npm run build - cdk synth +.. _define_app: -.. _create_widgets_service: +Defining the |cdk| App +---------------------- -Step 3: Create Widgets Service -============================== +|cdk| apps are classes that extend the :py:class:`App <@aws-cdk/cdk.App>` +class. Create an empty **App**: -Add the |ABP|, |LAM|, and |S3| packages to our app. +.. tabs:: + + .. group-tab:: C# + + In **Program.cs** + + .. code-block:: c# + + using Amazon.CDK; + + namespace HelloCdk + { + class Program + { + static void Main(string[] args) + { + var myApp = new App(); + myApp.Run(); + } + } + } + + .. group-tab:: JavaScript + + Create the file **bin/hello-cdk.js**: + + .. code-block:: js + + const cdk = require('@aws-cdk/cdk'); + + class MyApp extends cdk.App { + constructor() { + super(); + } + } + + new MyApp().run(); + + .. group-tab:: TypeScript + + Create the file **bin/hello-cdk.ts**: + + .. code-block:: ts + + import cdk = require('@aws-cdk/cdk'); + import { HelloCdkStack } from '../lib/hello-cdkstack'; + + const app = new cdk.App(); + new HelloCdkStack(app, 'HelloCdkStack'); + app.run(); + + Create the file **lib/hello-cdkstack.ts**: + + .. code-block:: ts + + import cdk = require('@aws-cdk/cdk'); + + export class HelloCdkStack extends cdk.Stack { + constructor(parent: cdk.App, name: string, props?: cdk.StackProps) { + super(parent, name, props); + + // The code that defines your stack goes here + } + } + + .. group-tab:: Java + + In **src/main/java/com/acme/MyApp.java**: + + .. code-block:: java + + package com.acme; + + import software.amazon.awscdk.App; + + import java.util.Arrays; + + public class MyApp { + public static void main(final String argv[]) { + App app = new App(); + + app.run(); + } + } + +.. _compile_code: + +Compiling the Code +------------------ + +If needed, compile the code: + +.. tabs:: + + .. group-tab:: C# + + Compile the code using your IDE or via the dotnet CLI: + + .. code-block:: sh + + dotnet build + + .. 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 + + Compile your code using your IDE or via the command line via **mvn**: + + .. code-block:: sh + + mvn compile + +You have now created your first |cdk| app. + +.. _list_stacks: + +Listing the Stacks in the App +============================= + +Use the |cdk| toolkit's **ls** command to list the stacks in the app. .. code-block:: sh - npm install @aws-cdk/aws-apigateway @aws-cdk/aws-lambda @aws-cdk/aws-s3 + cdk ls -Create the directory *lib* at the same level as the *bin* and *resources* -directories. +The result is just the name of the stack: .. code-block:: sh - mkdir lib + HelloCdkStack -Create the following Typescript file, *widget_service.ts*, -in the *lib* directory. +.. note:: -.. code-block:: ts + There is a known issue on Windows with the |cdk| .NET environment. + Whenever you use a **cdk** command, + it issues a node warning similar to the following: - import cdk = require('@aws-cdk/cdk'); - import apigateway = require('@aws-cdk/aws-apigateway'); - import lambda = require('@aws-cdk/aws-lambda'); - import s3 = require('@aws-cdk/aws-s3'); + .. code-block:: sh - export class WidgetService extends cdk.Construct { - constructor(parent: cdk.Construct, name: string) { - super(parent, name); + (node:27508) UnhandledPromiseRejectionWarning: Unhandled promise rejection + (rejection id: 1): Error: EPIPE: broken pipe, write + (node:27508) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. + In the future, promise rejections that are not handled will terminate the + Node.js process with a non-zero exit code. - // Use S3 bucket to store our widgets - const bucket = new s3.Bucket(this, 'WidgetStore'); + You can safely ignore this warning. - // Create a handler that calls the function main - // in the source file widgets(.js) in the resources directory - // to handle requests through API Gateway - const handler = new lambda.Function(this, 'WidgetHandler', { - runtime: lambda.Runtime.NodeJS810, - code: lambda.Code.directory('resources'), - handler: 'widgets.main', - environment: { - BUCKET: bucket.bucketName // So runtime has the bucket name - } - }); +.. _define_stack: - bucket.grantReadWrite(handler.role); +Define a Stack +============== - // Create an API Gateway REST API - const api = new apigateway.RestApi(this, 'widgets-api', { - restApiName: 'Widget Service', - description: 'This service serves widgets.' - }); +Define a stack and add it to the app. - // Pass the request to the handler - const getWidgetsIntegration = new apigateway.LambdaIntegration(handler); +.. tabs:: - // Use the getWidgetsIntegration when there is a GET request - api.root.addMethod('GET', getWidgetsIntegration); // GET / - } - } + .. group-tab:: C# -Save it and make sure it builds and creates a (still empty) stack. + Create **MyStack.cs**: -.. code-block:: sh + .. code-block:: c# - npm run build - cdk synth + using Amazon.CDK; -.. _add_service: + namespace HelloCdk + { + public class MyStack: Stack + { + public MyStack(App parent, string name) : base(parent, name, null) + { + } + } + } -Step 4: Add the Service to the App -================================== + In **Program.cs**: -To add the service to our app, -add the following line of code after the existing **import** statement in -*my_widget_service.ts*. + .. code-block:: c# + :emphasize-lines: 10 -.. code-block:: ts + using Amazon.CDK; - import widget_service = require('../lib/widget_service'); + namespace HelloCdk + { + class Program + { + static void Main(string[] args) + { + var myApp = new App(); + new MyStack(myApp, "hello-cdk"); + myApp.Run(); + } + } + } -Add the following line of code at the end of the constructor in *my_widget_service.ts*. + .. group-tab:: JavaScript -.. code-block:: ts + In **index.js**: - new widget_service.WidgetService(this, 'Widgets'); + .. code-block:: js + :emphasize-lines: 3,4,5,6,7,13 -Make sure it builds and creates a stack -(we don't show the stack as it's almost 300 lines). + const cdk = require('@aws-cdk/cdk'); -.. code-block:: sh + class MyStack extends cdk.Stack { + constructor(parent, id, props) { + super(parent, id, props); + } + } + + class MyApp extends cdk.App { + constructor(argv) { + super(argv); + + new MyStack(this, 'hello-cdk'); + } + } + + new MyApp().run(); + + .. group-tab:: TypeScript + + Nothing to do. + + .. group-tab:: Java + + In **src/main/java/com/acme/MyStack.java**: + + .. code-block:: java + + package com.acme; + + import software.amazon.awscdk.App; + import software.amazon.awscdk.Stack; + import software.amazon.awscdk.StackProps; + + public class MyStack extends Stack { + public MyStack(final App parent, final String name) { + this(parent, name, null); + } + + public MyStack(final App parent, final String name, final StackProps props) { + super(parent, name, props); + } + } - npm run build - cdk synth + In **src/main/java/com/acme/MyApp.java**: -.. _deploy_and_test: + .. code-block:: java + :emphasize-lines: 12 -Step 5: Deploy and Test the App -=============================== + package com.acme; -Before you can deploy your first |cdk| app, -you must bootstrap your deployment, -which creates some AWS infracture that the |cdk| -needs. -See the **bootstrap** section of the :doc:`tools` topic for details. + import software.amazon.awscdk.App; + import java.util.Arrays; + + public class MyApp { + public static void main(final String argv[]) { + App app = new App(); + + new MyStack(app, "hello-cdk"); + + app.run(); + } + } + +The initializer signature of **cdk.Stack** includes the 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 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 :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. + +Compile your program: + +.. tabs:: + + .. group-tab:: C# + + We configured *cdk.json* to run `dotnet run`, which + restores dependencies, builds, and runs your application, + run `cdk`. + + .. code-block:: sh + + cdk + + .. group-tab:: JavaScript + + Nothing to compile. + + .. group-tab:: TypeScript + + .. code-block:: sh + + npm run build + + .. group-tab:: Java + + .. code-block:: sh + + mvn compile + +.. _define_bucket: + +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. + +Install the **@aws-cdk/aws-s3** package: + +.. tabs:: + + .. group-tab:: C# + + .. code-block:: sh + + dotnet add package Amazon.CDK.AWS.S3 + + .. group-tab:: JavaScript + + .. code-block:: sh + + npm install @aws-cdk/aws-s3 + + .. group-tab:: TypeScript + + .. code-block:: sh + + npm install @aws-cdk/aws-s3 + + .. group-tab:: Java + + Edit your **pom.xml** file: + + .. code-block:: sh + + + software.amazon.awscdk + s3 + + + +Next, define an |S3| bucket in the stack. |S3| buckets are represented by +the :py:class:`Bucket <@aws-cdk/aws-s3.Bucket>` class: + +.. tabs:: + + .. group-tab:: C# + + Create **MyStack.cs**: + + .. code-block:: c# + :emphasize-lines: 2,10,11,12,13 + + using Amazon.CDK; + using Amazon.CDK.AWS.S3; + + namespace HelloCdk + { + public class MyStack : Stack + { + public MyStack(App parent, string name) : base(parent, name, null) + { + new Bucket(this, "MyFirstBucket", new BucketProps + { + Versioned = true + }); + } + } + } + + .. group-tab:: JavaScript + + In **index.js**: + + .. code-block:: js + :emphasize-lines: 2,8,9,10 + + const cdk = require('@aws-cdk/cdk'); + const s3 = require('@aws-cdk/aws-s3'); + + class MyStack extends cdk.Stack { + constructor(parent, id, props) { + super(parent, id, props); + + new s3.Bucket(this, 'MyFirstBucket', { + versioned: true + }); + } + } + + .. group-tab:: TypeScript + + In **lib/**: + + .. code-block:: ts + :emphasize-lines: 2,8,9,10 + + import cdk = require('@aws-cdk/cdk'); + import s3 = require('@aws-cdk/aws-s3'); + + export class HelloCdkStack extends cdk.Stack { + constructor(parent: cdk.App, id: string, props?: cdk.StackProps) { + super(parent, id, props); + + new s3.Bucket(this, 'MyFirstBucket', { + versioned: true + }); + } + } + + .. group-tab:: Java + + In **src/main/java/com/acme/MyStack.java**: + + .. code-block:: java + :emphasize-lines: 6,7,13,14,15 + + package com.acme; + + import software.amazon.awscdk.App; + import software.amazon.awscdk.Stack; + import software.amazon.awscdk.StackProps; + import software.amazon.awscdk.services.s3.Bucket; + import software.amazon.awscdk.services.s3.BucketProps; + + public class MyStack extends Stack { + public MyStack(final App parent, final String name) { + this(parent, name, null); + } + + public MyStack(final App parent, final String name, final StackProps props) { + super(parent, name, props); + + new Bucket(this, "MyFirstBucket", BucketProps.builder() + .withVersioned(true) + .build()); + } + } + +A few things to notice: + +* :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: + +.. tabs:: + + .. group-tab:: C# + + We configured *cdk.json* to run `dotnet run`, which + restores dependencies, builds, and runs your application, + run `cdk`. + + .. group-tab:: JavaScript + + Nothing to compile. + + .. group-tab:: TypeScript + + .. code-block:: sh + + npm run build + + .. group-tab:: Java + + .. code-block:: sh + + mvn compile + +.. _synthesize_template: + +Synthesize an |CFN| Template +============================ + +Synthesize a |cfn| template for the stack: .. code-block:: sh - cdk bootstrap + cdk synth HelloCdkStack + +.. note:: Since the |cdk| app only contains a single stack, you can omit :code:`HelloCdkStack`. + +This command executes the |cdk| app and synthesize an |CFN| template for the +**HelloCdkStack** stack. +You should see something similar to the following, +where VERSION is the version of the |cdk|. -Run the following command to deploy your app. +.. code-block:: yaml + + Resources: + MyFirstBucketB8884501: + Type: AWS::S3::Bucket + Properties: + VersioningConfiguration: + Status: Enabled + Metadata: + aws:cdk:path: HelloCdkStack/MyFirstBucket/Resource + CDKMetadata: + Type: AWS::CDK::Metadata + Properties: + Modules: "@aws-cdk/aws-codepipeline-api=VERSION,@aws-cdk/aws-events=VERSION,@aws-c\ + dk/aws-iam=VERSION,@aws-cdk/aws-kms=VERSION,@aws-cdk/aws-s3=VERSION,@aws-c\ + dk/aws-s3-notifications=VERSION,@aws-cdk/cdk=VERSION,@aws-cdk/cx-api=VERSION\ + .0,hello-cdk=0.1.0" + +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 +=================== + +Use **cdk deploy** to deploy the stack: .. code-block:: sh cdk deploy -If the deployment is successfull, -save the URL for your server, which appears in the last line in the window, -where GUID is an alpha-numeric GUID and REGION is your region. +The **deploy** command synthesizes an |CFN| template from the stack +and then invokes the |CFN| create/update API to deploy it into your AWS +account. The command displays information as it progresses. + +.. _modify_cde: + +Modifying the Code +================== + +Configure the bucket to use KMS managed encryption: + +.. tabs:: + + .. group-tab:: C# + + .. code-block:: c# + :emphasize-lines: 4 + + new Bucket(this, "MyFirstBucket", new BucketProps + { + Versioned = true, + Encryption = BucketEncryption.KmsManaged + }); + + .. group-tab:: JavaScript + + .. code-block:: js + :emphasize-lines: 3 + + new s3.Bucket(this, 'MyFirstBucket', { + versioned: true, + encryption: s3.BucketEncryption.KmsManaged + }); + + .. group-tab:: TypeScript + + .. code-block:: ts + :emphasize-lines: 3 + + new s3.Bucket(this, 'MyFirstBucket', { + versioned: true, + encryption: s3.BucketEncryption.KmsManaged + }); + + .. group-tab:: Java + + .. code-block:: java + :emphasize-lines: 3 + + new Bucket(this, "MyFirstBucket", BucketProps.builder() + .withVersioned(true) + .withEncryption(BucketEncryption.KmsManaged) + .build()); + +Compile the program: + +.. tabs:: + + .. group-tab:: C# + + We configured *cdk.json* to run `dotnet run`, which + restores dependencies, builds, and runs your application, + run `cdk`. + + .. group-tab:: JavaScript + + Nothing to compile. + + .. group-tab:: TypeScript + + .. code-block:: sh + + npm run build + + .. group-tab:: Java + + .. code-block:: sh + + mvn compile + +.. _prepare_deployment: + +Preparing for Deployment +======================== + +Before you deploy the updated stack, use the ``cdk diff`` command to evaluate +the difference between the |cdk| app and the deployed stack: .. code-block:: sh - https://GUID.execute-REGION.amazonaws.com/prod/ + cdk diff -You can test your app by getting the list of widgets (currently empty) by navigating to this URL in a -browser or use the following **curl** command. +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. +The output should look like the following: .. code-block:: sh - curl -X GET 'https://GUID.execute-REGION.amazonaws.com/prod' + [~] 🛠 Updating MyFirstBucketB8884501 (type: AWS::S3::Bucket) + └─ [+] .BucketEncryption: + └─ New value: {"ServerSideEncryptionConfiguration":[{"ServerSideEncryptionByDefault":{"SSEAlgorithm":"aws:kms"}}]} + +As you can see, the diff indicates that the +**ServerSideEncryptionConfiguration** property of the bucket is now set to +enable server-side encryption. -You can also open the |console|, -navigate to the |ABP| service, -find **Widget Service** in the list. -Select **GET** and **Test** to test the function. -Since we haven't stored any widgets yet, the output should be similar to the following -(there may be some slight differences in whitespace and quotation marks). +You can also see that the bucket is not going to be replaced but rather updated +("**Updating MyFirstBucketB8884501**"). + +Run **cdk deploy** to update the stack: .. code-block:: sh - { "widgets": [] } - -.. _adding_functions: - -Step 6: Add the Individual Widget Functions -=========================================== - -The next step is to create |LAM| functions to create, show, and delete -individual widgets. -Replace the existing **exports.main** function in *widgets.js* with the following code. - -.. code-block:: js - - exports.main = async function(event, context) { - try { - var method = event.httpMethod; - // Get name, if present - var widgetName = event.path.startsWith('/') ? event.path.substring(1) : event.path; - - if (method === "GET") { - // GET / to get the names of all widgets - if (event.path === "/") { - const data = await S3.listObjectsV2({ Bucket: bucketName }).promise(); - var body = { - widgets: data.Contents.map(function(e) { return e.Key }) - }; - return { - statusCode: 200, - headers: {}, - body: JSON.stringify(body) - }; - } - - if (widgetName) { - // GET /name to get info on widget name - const data = await S3.getObject({ Bucket: bucketName, Key: widgetName}).promise(); - var body = data.Body.toString('utf-8'); - - return { - statusCode: 200, - headers: {}, - body: JSON.stringify(body) - }; - } - } - - if (method === "POST") { - // POST /name - // Return error if we do not have a name - if (!widgetName) { - return { - statusCode: 400, - headers: {}, - body: "Widget name missing" - }; - } - - // Create some dummy data to populate object - const now = new Date(); - var data = widgetName + " created: " + now; - - var base64data = new Buffer(data, 'binary'); - - await S3.putObject({ - Bucket: bucketName, - Key: widgetName, - Body: base64data, - ContentType: 'application/json' - }).promise(); - - return { - statusCode: 200, - headers: {}, - body: JSON.stringify(event.widgets) - }; - } - - if (method === "DELETE") { - // DELETE /name - // Return an error if we do not have a name - if (!widgetName) { - return { - statusCode: 400, - headers: {}, - body: "Widget name missing" - }; - } - - await S3.deleteObject({ - Bucket: bucketName, Key: widgetName - }).promise(); - - return { - statusCode: 200, - headers: {}, - body: "Successfully deleted widget " + widgetName - }; - } - - // We got something besides a GET, POST, or DELETE - return { - statusCode: 400, - headers: {}, - body: "We only accept GET, POST, and DELETE, not " + method - }; - } catch(error) { - var body = error.stack || JSON.stringify(error, null, 2); - return { - statusCode: 400, - headers: {}, - body: body - } - } - } - -Wire these functions up to our |ABP| code in *widget_service.ts* -by adding the following code at the end of the constructor. - -.. code-block:: ts - - const widget = api.root.addResource('{name}'); - - // Add new widget to bucket with: POST /{name} - const postWidgetIntegration = new apigateway.LambdaIntegration(handler); - - // Get a specific widget from bucket with: GET /{name} - const getWidgetIntegration = new apigateway.LambdaIntegration(handler); - - // Remove a specific widget from the bucket with: DELETE /{name} - const deleteWidgetIntegration = new apigateway.LambdaIntegration(handler); - - widget.addMethod('POST', postWidgetIntegration); // POST /{name} - widget.addMethod('GET', getWidgetIntegration); // GET /{name} - widget.addMethod('DELETE', deleteWidgetIntegration); // DELETE /{name} - -Save, build, and deploy the app. - -Now we should be able to store, show, or delete an individual widget. -Use the following **curl** commands to list the widgets, -create the widget *dummy*, -list all of the widgets, -show the contents of *dummy* (it should show today's date), -and delete *dummy*, -and again show the list of widgets. + cdk deploy + +The toolkit updates the bucket configuration to enable server-side KMS +encryption for the bucket: .. code-block:: sh - curl -X GET 'https://GUID.execute-REGION.amazonaws.com/prod' - curl -X POST 'https://GUID.execute-REGION.amazonaws.com/prod/dummy' - curl -X GET 'https://GUID.execute-REGION.amazonaws.com/prod' - curl -X GET 'https://GUID.execute-REGION.amazonaws.com/prod/dummy' - curl -X DELETE 'https://GUID.execute-REGION.amazonaws.com/prod/dummy' - curl -X GET 'https://GUID.execute-REGION.amazonaws.com/prod' + ⏳ 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 + +.. _whats_next: + +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 `_ -You can also use the |ABP| console to test these functions. -You'll have to set the **name** entry to the name of an widget, -such as **dummy**. From 7957cd39c993b378351e792fe8ca54a3c3eb764b Mon Sep 17 00:00:00 2001 From: Doug-AWS Date: Thu, 6 Dec 2018 10:14:52 -0800 Subject: [PATCH 02/10] Refactoring docs; WIP --- docs/src/apples_example.rst | 16 +- docs/src/ecs_example.rst | 284 +++++++++++++-------------- docs/src/examples.rst | 204 +------------------ docs/src/manual.txt | 310 +++++++++++++++++++++++++++++ docs/src/template.txt | 72 +++++++ docs/src/tutorial.rst | 382 +----------------------------------- 6 files changed, 538 insertions(+), 730 deletions(-) create mode 100644 docs/src/manual.txt create mode 100644 docs/src/template.txt diff --git a/docs/src/apples_example.rst b/docs/src/apples_example.rst index ef2be74938b61..91294b154bacd 100644 --- a/docs/src/apples_example.rst +++ b/docs/src/apples_example.rst @@ -8,14 +8,20 @@ either express or implied. See the License for the specific language governing permissions and limitations under the License. -.. _tutorial: +.. _apples_example: ############## -|cdk| Tutorial + ############## -This topic steps you through creating the resources for a simple widget dispensing -service using the |cdk|. +This example walks you through creating the resources for a simple widget dispensing service. +It includes: + +* A |LAMlong| function + +* An |ABP| API to call our |LAM| function + +* An |S3| bucket that contains our |LAM| function code .. _overview: @@ -26,7 +32,7 @@ This tutorial contains the following steps. 1. Create a |cdk| app -2. Create a |LAMlong| function that gets a list of widgets with: GET / +2. Create a |LAM| function that gets a list of widgets with: GET / 3. Create the service that calls the |LAM| function diff --git a/docs/src/ecs_example.rst b/docs/src/ecs_example.rst index 4269ac53ab6fa..d5202c9267e61 100644 --- a/docs/src/ecs_example.rst +++ b/docs/src/ecs_example.rst @@ -8,211 +8,193 @@ either express or implied. See the License for the specific language governing permissions and limitations under the License. -.. _cdk_examples: +.. _ecs_example: -############## -|cdk| Examples -############## +############# +|ECS| Example +############# -This topic contains some usage examples to help you get started understanding -the |cdk|. +This example walks you through creating a Fargate service running on an ECS cluster fronted by an internet-facing +application load balancer. -.. We'll include this if we ever implement DeploymentPipeline - _multiple_stacks_example: +|ECSlong| (|ECS|) is a highly scalable, fast, container management service +that makes it easy to run, stop, and manage Docker containers on a cluster. +You can host your cluster on a serverless infrastructure that is managed by +|ECS| by launching your services or tasks using the Fargate launch type. +For more control you can host your tasks on a cluster of +|EC2long| (|EC2|) instances that you manage by using the EC2 launch type. - Creating an App with Multiple Stacks - ==================================== +This example shows you how to launch some services using the Fargate launch type. +If you've ever used the console to create a Fargate service, +you know that there are many steps you must follow to accomplish that task. +AWS has a number of tutorials and documentation topics that walk you through +creating a Fargate service, +including: - The following example creates the following stacks and one deployment pipeline: +* `How to Deploy Docker Containers - AWS `_ - - **Dev** uses the default environment - - **PreProd** in the **us-west-2** Region - - **NAEast** in the **us-east-1** Region - - **NAWest** in the **us-west-2** Region - - **EU** in the **eu-west-1** Region - - **DeploymentPipeline** in the **us-east-1** Region +* `Setting up with Amazon ECS `_ and + `Getting Started with Amazon ECS using Fargate `_ - Implement the class **MyStack** in the *my-stack* sub-folder, - that extends the |stack-class| class - (this is the same code as shown in the :doc:`concepts` topic). +This example creates a similar Fargate service in |cdk| code. - code-block:: js +Since |ECS| can be used with a number of AWS services, +you should understand how the |ECS| construct that we use in this example +gives you a leg up on using AWS services by providing the following benefits: - import { Stack, StackProps } from '@aws-cdk/cdk' +* Automatically configures a load balancer. - interface MyStackProps extends StackProps { - encryptedStorage: boolean; - } +* Automatic security group opening for load balancers, + which enables load balancers to communicate with instances + without you explictly creating a security group. - export class MyStack extends Stack { - constructor(parent: Construct, name: string, props?: MyStackProps) { - super(parent, name, props); +* Automatic ordering dependency between service and load balancer attaching to a target group, + where the |cdk| enforces the correct order of creating the listener before an instance is created - new MyStorageLayer(this, 'Storage', { encryptedStorage: props.encryptedStorage }); - new MyControlPlane(this, 'CPlane'); - new MyDataPlane(this, 'DPlane'); - } - } +* Automatic userdata configuration on auto-scaling group, + which creates the correct configuration to associate a cluster to AMI(s). + +* Early validation of parameter combinations, which exposes |CFN| issues earlier, thus saving you deployment time. + For example, depending upon the task, it is easy to mis-configure the memory settings. + Previously you would not encounter an error until you deployed your app, + but now the |cdk| can detect a misconfiguration and emit an error when you synthesize your app. - Implement the class **DeploymentPipeline** in the *my-deployment* sub-folder, - that extends the |stack-class| class - (this is the same code as shown in the :doc:`concepts` topic). +* Automatically adds permissions for |ECR| if you use an image from |ECR| + When you use an image from |ECR|, the |cdk| adds the correct permissions. - code-block:: js +* Automatic autoscaling + The |cdk| supplies a method so you can autoscaling instances when you use an |EC2| cluster; + this functionality is done automatically when you use an instance in a Fargate cluster. - Use **MyStack** and **DeploymentPipeline** to create the stacks and deployment pipeline. + In addition, the |cdk| will prevent instances from being deleted when + autoscaling tries to kill an instance, + but either a task is running or is scheduled on that instance. - code-block:: js + Previously, you had to create a Lambda function to have this functionality. + +* Asset support, so that you can deploy source from your machine to |ECS| in one step + Previously, to use application source you had to perform a number of manual steps + (upload to |ECR|, create Docker image, etc.). + +.. _creating_ecs_l2_example_1: - import { App } from '@aws-cdk/cdk' - import { MyStack } from './my-stack' - import { DeploymentPipeline } from './my-deployment' +Step 1: Create the Directory and Initialize the |cdk| +----------------------------------------------------- - const app = new App(); +Let's start with creating a new directory to hold our |cdk| code +and create a new app in that directory. - // Use the default environment - new MyStack(app, { name: 'Dev' }); +.. code-block:: sh - // Pre-production stack - const preProd = new MyStack(app, { - name: 'PreProd', - env: { region: 'us-west-2' }, - preProd: true - }); + mkdir MyEcsConstruct + cd MyEcsConstruct - // Production stacks - const prod = [ - new MyStack(app, { - name: 'NAEast', - env: { region: 'us-east-1' } - }), +.. tabs:: - new MyStack(app, { - name: 'NAWest', - env: { region: 'us-west-2' } - }), + .. group-tab:: TypeScript - new MyStack(app, { - name: 'EU', - env: { region: 'eu-west-1' }, - encryptedStorage: true - }) - ] + .. code-block:: sh - // CI/CD pipeline stack - new DeploymentPipeline(app, { - env: { region: 'us-east-1' }, - strategy: DeploymentStrategy.Waved, - preProdStages: [ preProd ], - prodStages: prod - }); + cdk init --language typescript - app.run(); + Build the app and confirm that it creates an empty stack. -.. _dynamodb_example: + .. code-block:: sh -Creating a |DDB| Table -====================== + npm run build + cdk synth -The following example creates a -|DDB| table with the partition key **Alias** -and sort key **Timestamp**. + You should see a stack like the following, + where CDK-VERSION is the version of the CDK. -.. code-block:: js + .. code-block:: sh - import dynamodb = require('@aws-cdk/aws-dynamodb'); - import cdk = require('@aws-cdk/cdk'); + Resources: + CDKMetadata: + Type: 'AWS::CDK::Metadata' + Properties: + Modules: @aws-cdk/cdk=CDK-VERSION,@aws-cdk/cx-api=CDK-VERSION,my_ecs_construct=0.1.0 - class MyStack extends cdk.Stack { - constructor(parent: cdk.App, name: string, props?: cdk.StackProps) { - super(parent, name, props); +.. _creating_ecs_l2_example_2: - const table = new dynamodb.Table(this, 'Table', { - tableName: 'MyAppTable', - readCapacity: 5, - writeCapacity: 5 - }); +Step 2: Add the |EC2| and |ECS| Packages +---------------------------------------- - table.addPartitionKey({ name: 'Alias', type: dynamodb.AttributeType.String }); - table.addSortKey({ name: 'Timestamp', type: dynamodb.AttributeType.String }); - } - } +Install support for |EC2| and |ECS|. - const app = new cdk.App(); +.. tabs:: - new MyStack(app, 'MyStack'); + .. group-tab:: TypeScript - app.run(); + .. code-block:: sh -.. _creating_rds_example: + npm install @aws-cdk/aws-ec2 @aws-cdk/aws-ecs -Creating an |RDS| Database -========================== +.. _creating_ecs_l2_example_3: -The following example creates the Aurora database **MyAuroraDatabase**. +Step 3: Create a Fargate Service +-------------------------------- -.. code-block:: js +There are two different ways of running your container tasks with |ECS|: - import ec2 = require('@aws-cdk/aws-ec2'); - import rds = require('@aws-cdk/aws-rds'); - import cdk = require('@aws-cdk/cdk'); +- Using the **Fargate** launch type, + where |ECS| manages the physical machines that your containers are running on for you +- Using the **EC2** launch type, where you do the managing, such as specifying autoscaling - class MyStack extends cdk.Stack { - constructor(parent: cdk.App, name: string, props?: cdk.StackProps) { - super(parent, name, props); +The following example creates a Fargate service running on an ECS cluster fronted by an internet-facing +application load balancer. - const vpc = new ec2.VpcNetwork(this, 'VPC'); +.. tabs:: - new rds.DatabaseCluster(this, 'MyRdsDb', { - defaultDatabaseName: 'MyAuroraDatabase', - masterUser: { - username: 'admin', - password: '123456' - }, - engine: rds.DatabaseClusterEngine.Aurora, - instanceProps: { - instanceType: new ec2.InstanceTypePair(ec2.InstanceClass.Burstable2, ec2.InstanceSize.Small), - vpc: vpc, - vpcPlacement: { - subnetsToUse: ec2.SubnetType.Public - } - } - }); - } - } + .. group-tab:: TypeScript - const app = new cdk.App(); + Add the following import statements to *lib/my_ecs_construct-stack.ts*: - new MyStack(app, 'MyStack'); + .. code-block:: typescript - app.run(); + import ec2 = require('@aws-cdk/aws-ec2'); + import ecs = require('@aws-cdk/aws-ecs'); -.. _creating_s3_example: + Replace the comment at the end of the constructor with the following code: -Creating an |S3| Bucket -======================= + .. code-block:: typescript -The following example creates the |S3| bucket **MyS3Bucket** with server-side KMS -encryption provided by |S3|. + const vpc = new ec2.VpcNetwork(this, 'MyVpc', { + maxAZs: 3 // Default is all AZs in region + }); -.. code-block:: js + const cluster = new ecs.Cluster(this, 'MyCluster', { + vpc: vpc + }); - import s3 = require('@aws-cdk/aws-s3'); - import cdk = require('@aws-cdk/cdk'); + // Create a load-balanced Fargate service and make it public + new ecs.LoadBalancedFargateService(this, 'MyFargateService', { + cluster: cluster, // Required + cpu: '512', // Default is 256 + desiredCount: 6, // Default is 1 + image: ecs.ContainerImage.fromDockerHub('amazon/amazon-ecs-sample'), // Required + memoryMiB: '2048', // Default is 512 + publicLoadBalancer: true // Default is false + }); - class MyStack extends cdk.Stack { - constructor(parent: cdk.App, name: string, props?: cdk.StackProps) { - super(parent, name, props); + Save it and make sure it builds and creates a stack. - new s3.Bucket(this, 'MyBucket', { - bucketName: 'MyS3Bucket', - encryption: s3.BucketEncryption.KmsManaged - }); - } - } + .. code-block:: sh - const app = new cdk.App(); + npm run build + cdk synth - new MyStack(app, 'MyStack'); + The stack is hundreds of lines, so we won't show it here. + The stack should contain one default instance, a private subnet and a public subnet + for the three availability zones, and a security group. - app.run() + Deploy the stack. + + .. code-block:: sh + + cdk deploy + + |CFN| displays information about the dozens of steps that + it takes as it deploys your app. + +That's how easy it is to create a Fargate service to run a Docker image. diff --git a/docs/src/examples.rst b/docs/src/examples.rst index 4269ac53ab6fa..9c4ff71b776fd 100644 --- a/docs/src/examples.rst +++ b/docs/src/examples.rst @@ -17,202 +17,14 @@ This topic contains some usage examples to help you get started understanding the |cdk|. -.. We'll include this if we ever implement DeploymentPipeline - _multiple_stacks_example: +* :doc:`ecs_example` walks you through creating a Fargate service running on an ECS cluster fronted by an internet-facing +application load balancer. - Creating an App with Multiple Stacks - ==================================== +* :doc:`apples_example` walks you through creating the resources for a simple widget dispensing service. - The following example creates the following stacks and one deployment pipeline: +.. toctree:: + :maxdepth: 2 + :hidden: - - **Dev** uses the default environment - - **PreProd** in the **us-west-2** Region - - **NAEast** in the **us-east-1** Region - - **NAWest** in the **us-west-2** Region - - **EU** in the **eu-west-1** Region - - **DeploymentPipeline** in the **us-east-1** Region - - Implement the class **MyStack** in the *my-stack* sub-folder, - that extends the |stack-class| class - (this is the same code as shown in the :doc:`concepts` topic). - - code-block:: js - - import { Stack, StackProps } from '@aws-cdk/cdk' - - interface MyStackProps extends StackProps { - encryptedStorage: boolean; - } - - export class MyStack extends Stack { - constructor(parent: Construct, name: string, props?: MyStackProps) { - super(parent, name, props); - - new MyStorageLayer(this, 'Storage', { encryptedStorage: props.encryptedStorage }); - new MyControlPlane(this, 'CPlane'); - new MyDataPlane(this, 'DPlane'); - } - } - - Implement the class **DeploymentPipeline** in the *my-deployment* sub-folder, - that extends the |stack-class| class - (this is the same code as shown in the :doc:`concepts` topic). - - code-block:: js - - Use **MyStack** and **DeploymentPipeline** to create the stacks and deployment pipeline. - - code-block:: js - - import { App } from '@aws-cdk/cdk' - import { MyStack } from './my-stack' - import { DeploymentPipeline } from './my-deployment' - - const app = new App(); - - // Use the default environment - new MyStack(app, { name: 'Dev' }); - - // Pre-production stack - const preProd = new MyStack(app, { - name: 'PreProd', - env: { region: 'us-west-2' }, - preProd: true - }); - - // Production stacks - const prod = [ - new MyStack(app, { - name: 'NAEast', - env: { region: 'us-east-1' } - }), - - new MyStack(app, { - name: 'NAWest', - env: { region: 'us-west-2' } - }), - - new MyStack(app, { - name: 'EU', - env: { region: 'eu-west-1' }, - encryptedStorage: true - }) - ] - - // CI/CD pipeline stack - new DeploymentPipeline(app, { - env: { region: 'us-east-1' }, - strategy: DeploymentStrategy.Waved, - preProdStages: [ preProd ], - prodStages: prod - }); - - app.run(); - -.. _dynamodb_example: - -Creating a |DDB| Table -====================== - -The following example creates a -|DDB| table with the partition key **Alias** -and sort key **Timestamp**. - -.. code-block:: js - - import dynamodb = require('@aws-cdk/aws-dynamodb'); - import cdk = require('@aws-cdk/cdk'); - - class MyStack extends cdk.Stack { - constructor(parent: cdk.App, name: string, props?: cdk.StackProps) { - super(parent, name, props); - - const table = new dynamodb.Table(this, 'Table', { - tableName: 'MyAppTable', - readCapacity: 5, - writeCapacity: 5 - }); - - table.addPartitionKey({ name: 'Alias', type: dynamodb.AttributeType.String }); - table.addSortKey({ name: 'Timestamp', type: dynamodb.AttributeType.String }); - } - } - - const app = new cdk.App(); - - new MyStack(app, 'MyStack'); - - app.run(); - -.. _creating_rds_example: - -Creating an |RDS| Database -========================== - -The following example creates the Aurora database **MyAuroraDatabase**. - -.. code-block:: js - - import ec2 = require('@aws-cdk/aws-ec2'); - import rds = require('@aws-cdk/aws-rds'); - import cdk = require('@aws-cdk/cdk'); - - class MyStack extends cdk.Stack { - constructor(parent: cdk.App, name: string, props?: cdk.StackProps) { - super(parent, name, props); - - const vpc = new ec2.VpcNetwork(this, 'VPC'); - - new rds.DatabaseCluster(this, 'MyRdsDb', { - defaultDatabaseName: 'MyAuroraDatabase', - masterUser: { - username: 'admin', - password: '123456' - }, - engine: rds.DatabaseClusterEngine.Aurora, - instanceProps: { - instanceType: new ec2.InstanceTypePair(ec2.InstanceClass.Burstable2, ec2.InstanceSize.Small), - vpc: vpc, - vpcPlacement: { - subnetsToUse: ec2.SubnetType.Public - } - } - }); - } - } - - const app = new cdk.App(); - - new MyStack(app, 'MyStack'); - - app.run(); - -.. _creating_s3_example: - -Creating an |S3| Bucket -======================= - -The following example creates the |S3| bucket **MyS3Bucket** with server-side KMS -encryption provided by |S3|. - -.. code-block:: js - - import s3 = require('@aws-cdk/aws-s3'); - import cdk = require('@aws-cdk/cdk'); - - class MyStack extends cdk.Stack { - constructor(parent: cdk.App, name: string, props?: cdk.StackProps) { - super(parent, name, props); - - new s3.Bucket(this, 'MyBucket', { - bucketName: 'MyS3Bucket', - encryption: s3.BucketEncryption.KmsManaged - }); - } - } - - const app = new cdk.App(); - - new MyStack(app, 'MyStack'); - - app.run() + ECS Example + Apples Example diff --git a/docs/src/manual.txt b/docs/src/manual.txt new file mode 100644 index 0000000000000..4853c3957c1f6 --- /dev/null +++ b/docs/src/manual.txt @@ -0,0 +1,310 @@ + + .. _manual_project: + + Manually Creating a Project + =========================== + + In this section we create a new |cdk| project using explicit command-line commands. + Be sure to navigate to the *hello-cdk* directory before you start. + + .. _initializing_manually: + + Initializing the Project + ------------------------ + + Create an empty project for the |cdk| app. + + .. tabs:: + + .. group-tab:: C# + + Create a new console application. + + .. code-block:: sh + + dotnet new console + + .. group-tab:: JavaScript + + Create an initial npm **package.json** file: + + .. code-block:: sh + + npm init -y # creates package.json + + Create a **.gitignore** file with the following content: + + .. code-block:: sh + + *.js + node_modules + + .. group-tab:: TypeScript + + Create an initial npm **package.json** file: + + .. code-block:: sh + + npm init -y # creates package.json + + Create a **.gitignore** file with the following content: + + .. code-block:: sh + + *.js + *.d.ts + node_modules + + Add the `build` and `watch` TypeScript commands to **package.json**: + + .. code-block:: json + + { + "scripts": { + "build": "tsc", + "watch": "tsc -w" + } + } + + Create a minimal **tsconfig.json**: + + .. code-block:: json + + { + "compilerOptions": { + "target": "es2018", + "module": "commonjs" + } + } + + Create a minimal **cdk.json** (this saves you from including `--app node bin/hello-cdk.js` in every `cdk` command): + + .. code-block:: json + + { + "app": "node bin/hello-cdk.js" + } + + .. group-tab:: Java + + Create a **.gitignore** file with the following content: + + .. code-block:: sh + + .classpath.txt + target + .classpath + .project + .idea + .settings + .vscode + *.iml + + 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_core: + + Adding the CDK Core as a Dependency + ----------------------------------- + + Install the |cdk| core library (:py:mod:`@aws-cdk/cdk`) + This library includes the basic classes needed to write |cdk| stacks and apps. + + .. tabs:: + + .. group-tab:: C# + + Install the **Amazon.CDK NuGet** package: + + .. code-block:: sh + + dotnet add package Amazon.CDK + + .. group-tab:: JavaScript + + Install the **@aws-cdk/cdk** package: + + .. code-block:: sh + + npm install @aws-cdk/cdk + + .. group-tab:: TypeScript + + Install the **@aws-cdk/cdk** package: + + .. code-block:: sh + + npm install @aws-cdk/cdk + + .. group-tab:: Java + + Add the following to your project's `pom.xml` file: + + .. code-block:: xml + + + + software.amazon.awscdk + cdk + + + + + .. _define_app: + + Defining the |cdk| App + ---------------------- + + |cdk| apps are classes that extend the :py:class:`App <@aws-cdk/cdk.App>` + class. Create an empty **App**: + + .. tabs:: + + .. group-tab:: C# + + In **Program.cs** + + .. code-block:: c# + + using Amazon.CDK; + + namespace HelloCdk + { + class Program + { + static void Main(string[] args) + { + var myApp = new App(); + myApp.Run(); + } + } + } + + .. group-tab:: JavaScript + + Create the file **bin/hello-cdk.js**: + + .. code-block:: js + + const cdk = require('@aws-cdk/cdk'); + + class MyApp extends cdk.App { + constructor() { + super(); + } + } + + new MyApp().run(); + + .. group-tab:: TypeScript + + Create the file **bin/hello-cdk.ts**: + + .. code-block:: ts + + import cdk = require('@aws-cdk/cdk'); + import { HelloCdkStack } from '../lib/hello-cdkstack'; + + const app = new cdk.App(); + new HelloCdkStack(app, 'HelloCdkStack'); + app.run(); + + Create the file **lib/hello-cdkstack.ts**: + + .. code-block:: ts + + import cdk = require('@aws-cdk/cdk'); + + export class HelloCdkStack extends cdk.Stack { + constructor(parent: cdk.App, name: string, props?: cdk.StackProps) { + super(parent, name, props); + + // The code that defines your stack goes here + } + } + + .. group-tab:: Java + + In **src/main/java/com/acme/MyApp.java**: + + .. code-block:: java + + package com.acme; + + import software.amazon.awscdk.App; + + import java.util.Arrays; + + public class MyApp { + public static void main(final String argv[]) { + App app = new App(); + + app.run(); + } + } + + .. _compile_code: + + Compiling the Code + ------------------ + + If needed, compile the code: + + .. tabs:: + + .. group-tab:: C# + + Compile the code using your IDE or via the dotnet CLI: + + .. code-block:: sh + + dotnet build + + .. 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 + + Compile your code using your IDE or via the command line via **mvn**: + + .. code-block:: sh + + mvn compile + + You have now created your first |cdk| app. diff --git a/docs/src/template.txt b/docs/src/template.txt new file mode 100644 index 0000000000000..e7cff11924095 --- /dev/null +++ b/docs/src/template.txt @@ -0,0 +1,72 @@ + + .. _cdk_init_project: + + Creating a Project from the Template + ==================================== + + As mentioned previously, + you can use the :code:`cdk init` command to create a skeleton project from a + template in any of the supported languages. + In this section we'll do just that. + + .. _initialize: + + Initializing the Project + ------------------------ + + Run the `cdk init` command to initialize an empty project. + The |cdk| contains templates for all of the supported languages. + To create an empty (no AWS resources in the resulting |CFN| stack), + run the following command, where LANGUAGE is one of the supported programming languages: + **csharp** (C#), **java** (Java), or **typescript** (TypeScript). + + .. code-block:: sh + + cdk init --language LANGUAGE + + .. _compile_project: + + Compiling the Project + --------------------- + + If needed, compile the code: + + .. tabs:: + + .. group-tab:: C# + + Compile the code using your IDE or via the dotnet CLI: + + .. code-block:: sh + + dotnet build + + .. 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 + + Compile your code using your IDE or via the command line via **mvn**: + + .. code-block:: sh + + mvn compile + + You have now created your first |cdk| app. diff --git a/docs/src/tutorial.rst b/docs/src/tutorial.rst index 115b7332d80aa..394aa65d1ef89 100644 --- a/docs/src/tutorial.rst +++ b/docs/src/tutorial.rst @@ -28,389 +28,15 @@ All of these instructions use this directory: cd hello-cdk git init -.. _cdk_init_project: - -Creating a Project from the Template -==================================== - -As mentioned previously, -you can use the :code:`cdk init` command to create a skeleton project from a -template in any of the supported languages. -In this section we'll do just that. - -.. _initialize: - -Initializing the Project ------------------------- - -Run the `cdk init` command to initialize an empty project. -The |cdk| contains templates for all of the supported languages. -To create an empty (no AWS resources in the resulting |CFN| stack), -run the following command, where LANGUAGE is one of the supported programming languages: -**csharp** (C#), **java** (Java), or **typescript** (TypeScript). - -.. code-block:: sh - - cdk init --language LANGUAGE - -.. _compile_project: - -Compiling the Project ---------------------- - -If needed, compile the code: - -.. tabs:: - - .. group-tab:: C# - - Compile the code using your IDE or via the dotnet CLI: - - .. code-block:: sh - - dotnet build - - .. 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 - - Compile your code using your IDE or via the command line via **mvn**: - - .. code-block:: sh - - mvn compile - -You have now created your first |cdk| app. -Since the next section manually creates the same, empty project, -you can skip forward to `Listing the Stacks in the App`_. - -.. _manual_project: - -Manually Creating a Project -=========================== - -In this section we create a new |cdk| project using explicit command-line commands. -Be sure to navigate to the *hello-cdk* directory before you start. - -.. _initializing_manually: - -Initializing the Project ------------------------- - -Create an empty project for the |cdk| app. - -.. tabs:: - - .. group-tab:: C# - - Create a new console application. - - .. code-block:: sh - - dotnet new console - - .. group-tab:: JavaScript - - Create an initial npm **package.json** file: - - .. code-block:: sh - - npm init -y # creates package.json - - Create a **.gitignore** file with the following content: - - .. code-block:: sh - - *.js - node_modules - - .. group-tab:: TypeScript - - Create an initial npm **package.json** file: - - .. code-block:: sh - - npm init -y # creates package.json - - Create a **.gitignore** file with the following content: - - .. code-block:: sh - - *.js - *.d.ts - node_modules - - Add the `build` and `watch` TypeScript commands to **package.json**: - - .. code-block:: json - - { - "scripts": { - "build": "tsc", - "watch": "tsc -w" - } - } - - Create a minimal **tsconfig.json**: - - .. code-block:: json - - { - "compilerOptions": { - "target": "es2018", - "module": "commonjs" - } - } - - Create a minimal **cdk.json** (this saves you from including `--app node bin/hello-cdk.js` in every `cdk` command): - - .. code-block:: json - - { - "app": "node bin/hello-cdk.js" - } - - .. group-tab:: Java - - Create a **.gitignore** file with the following content: - - .. code-block:: sh - - .classpath.txt - target - .classpath - .project - .idea - .settings - .vscode - *.iml - - 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_core: - -Adding the CDK Core as a Dependency ------------------------------------ - -Install the |cdk| core library (:py:mod:`@aws-cdk/cdk`) -This library includes the basic classes needed to write |cdk| stacks and apps. - -.. tabs:: - - .. group-tab:: C# - - Install the **Amazon.CDK NuGet** package: - - .. code-block:: sh - - dotnet add package Amazon.CDK - - .. group-tab:: JavaScript - - Install the **@aws-cdk/cdk** package: - - .. code-block:: sh - - npm install @aws-cdk/cdk - - .. group-tab:: TypeScript - - Install the **@aws-cdk/cdk** package: - - .. code-block:: sh - - npm install @aws-cdk/cdk - - .. group-tab:: Java - - Add the following to your project's `pom.xml` file: - - .. code-block:: xml - - - - software.amazon.awscdk - cdk - - - - -.. _define_app: - -Defining the |cdk| App ----------------------- - -|cdk| apps are classes that extend the :py:class:`App <@aws-cdk/cdk.App>` -class. Create an empty **App**: - -.. tabs:: - - .. group-tab:: C# - - In **Program.cs** - - .. code-block:: c# - - using Amazon.CDK; - - namespace HelloCdk - { - class Program - { - static void Main(string[] args) - { - var myApp = new App(); - myApp.Run(); - } - } - } - - .. group-tab:: JavaScript - - Create the file **bin/hello-cdk.js**: - - .. code-block:: js - - const cdk = require('@aws-cdk/cdk'); - - class MyApp extends cdk.App { - constructor() { - super(); - } - } - - new MyApp().run(); - - .. group-tab:: TypeScript - - Create the file **bin/hello-cdk.ts**: - - .. code-block:: ts - - import cdk = require('@aws-cdk/cdk'); - import { HelloCdkStack } from '../lib/hello-cdkstack'; - - const app = new cdk.App(); - new HelloCdkStack(app, 'HelloCdkStack'); - app.run(); - - Create the file **lib/hello-cdkstack.ts**: - - .. code-block:: ts - - import cdk = require('@aws-cdk/cdk'); - - export class HelloCdkStack extends cdk.Stack { - constructor(parent: cdk.App, name: string, props?: cdk.StackProps) { - super(parent, name, props); - - // The code that defines your stack goes here - } - } - - .. group-tab:: Java - - In **src/main/java/com/acme/MyApp.java**: - - .. code-block:: java - - package com.acme; - - import software.amazon.awscdk.App; - - import java.util.Arrays; - - public class MyApp { - public static void main(final String argv[]) { - App app = new App(); - - app.run(); - } - } - -.. _compile_code: - -Compiling the Code ------------------- - -If needed, compile the code: - .. tabs:: - .. group-tab:: C# - - Compile the code using your IDE or via the dotnet CLI: - - .. code-block:: sh - - dotnet build - - .. group-tab:: JavaScript - - No need to compile - - .. group-tab:: TypeScript + .. group-tab:: template - To compile your program from **.ts** to **.js**: + .. include:: template.txt - .. 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 - - Compile your code using your IDE or via the command line via **mvn**: - - .. code-block:: sh - - mvn compile + .. group-tab:: manual -You have now created your first |cdk| app. + .. include:: manual.txt .. _list_stacks: From d4a66cb4f548e9808bb558c78f55b4e25e41bba7 Mon Sep 17 00:00:00 2001 From: Doug-AWS Date: Thu, 6 Dec 2018 12:46:52 -0800 Subject: [PATCH 03/10] Wrong tag for template/manual tabs --- docs/src/template.txt | 4 +--- docs/src/tutorial.rst | 16 ++++++++-------- 2 files changed, 9 insertions(+), 11 deletions(-) diff --git a/docs/src/template.txt b/docs/src/template.txt index e7cff11924095..9ca976f8b834c 100644 --- a/docs/src/template.txt +++ b/docs/src/template.txt @@ -4,10 +4,8 @@ Creating a Project from the Template ==================================== - As mentioned previously, - you can use the :code:`cdk init` command to create a skeleton project from a + In this section we use the :code:`cdk init` command to create a skeleton project from a template in any of the supported languages. - In this section we'll do just that. .. _initialize: diff --git a/docs/src/tutorial.rst b/docs/src/tutorial.rst index 394aa65d1ef89..6cd796cfc43f6 100644 --- a/docs/src/tutorial.rst +++ b/docs/src/tutorial.rst @@ -10,13 +10,13 @@ .. _tutorial: -###################################### -Tutorial: Creating a |cdk| Application -###################################### +####################################### +Tutorial: Creating an |cdk| Application +####################################### -This topic walks you through creating and deploying a |cdk| app, -by using the `cdk init` command, as described in `Creating a Project from the Template`_, -or manually, as described in `Manually Creating a Project`_. +This topic walks you through creating and deploying an |cdk| app, +by using the `cdk init` command, as described in the **Template** tab, +or manually, as described in the **Manual** tab. In either case, the first step is to create the directory for your project, with an empty Git repository. @@ -30,11 +30,11 @@ All of these instructions use this directory: .. tabs:: - .. group-tab:: template + .. tab:: template .. include:: template.txt - .. group-tab:: manual + .. tab:: manual .. include:: manual.txt From 1e167e6eff6f34d9ee49fcb2b08450ab4d83cd02 Mon Sep 17 00:00:00 2001 From: Doug-AWS Date: Thu, 6 Dec 2018 13:37:11 -0800 Subject: [PATCH 04/10] Incorporated template.txt and manual.txt --- docs/src/tutorial.rst | 382 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 379 insertions(+), 3 deletions(-) diff --git a/docs/src/tutorial.rst b/docs/src/tutorial.rst index 6cd796cfc43f6..baebd38e23d8c 100644 --- a/docs/src/tutorial.rst +++ b/docs/src/tutorial.rst @@ -31,12 +31,388 @@ All of these instructions use this directory: .. tabs:: .. tab:: template - - .. include:: template.txt + + .. _cdk_init_project: + + Creating a Project from the Template + ==================================== + + In this section we use the :code:`cdk init` command to create a skeleton project from a + template in any of the supported languages. + + .. _initialize: + + Initializing the Project + ------------------------ + + Run the `cdk init` command to initialize an empty project. + The |cdk| contains templates for all of the supported languages. + To create an empty (no AWS resources in the resulting |CFN| stack), + run the following command, where LANGUAGE is one of the supported programming languages: + **csharp** (C#), **java** (Java), or **typescript** (TypeScript). + + .. code-block:: sh + + cdk init --language LANGUAGE + + .. _compile_project: + + Compiling the Project + --------------------- + + If needed, compile the code: + + .. tabs:: + + .. group-tab:: C# + + Compile the code using your IDE or via the dotnet CLI: + + .. code-block:: sh + + dotnet build + + .. 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 + + Compile your code using your IDE or via the command line via **mvn**: + + .. code-block:: sh + + mvn compile + + You have now created your first |cdk| app. .. tab:: manual - .. include:: manual.txt + .. _manual_project: + + Manually Creating a Project + =========================== + + In this section we create a new |cdk| project using explicit command-line commands. + Be sure to navigate to the *hello-cdk* directory before you start. + + .. _initializing_manually: + + Initializing the Project + ------------------------ + + Create an empty project for the |cdk| app. + + .. tabs:: + + .. group-tab:: C# + + Create a new console application. + + .. code-block:: sh + + dotnet new console + + .. group-tab:: JavaScript + + Create an initial npm **package.json** file: + + .. code-block:: sh + + npm init -y # creates package.json + + Create a **.gitignore** file with the following content: + + .. code-block:: sh + + *.js + node_modules + + .. group-tab:: TypeScript + + Create an initial npm **package.json** file: + + .. code-block:: sh + + npm init -y # creates package.json + + Create a **.gitignore** file with the following content: + + .. code-block:: sh + + *.js + *.d.ts + node_modules + + Add the `build` and `watch` TypeScript commands to **package.json**: + + .. code-block:: json + + { + "scripts": { + "build": "tsc", + "watch": "tsc -w" + } + } + + Create a minimal **tsconfig.json**: + + .. code-block:: json + + { + "compilerOptions": { + "target": "es2018", + "module": "commonjs" + } + } + + Create a minimal **cdk.json** (this saves you from including `--app node bin/hello-cdk.js` in every `cdk` command): + + .. code-block:: json + + { + "app": "node bin/hello-cdk.js" + } + + .. group-tab:: Java + + Create a **.gitignore** file with the following content: + + .. code-block:: sh + + .classpath.txt + target + .classpath + .project + .idea + .settings + .vscode + *.iml + + 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_core: + + Adding the CDK Core as a Dependency + ----------------------------------- + + Install the |cdk| core library (:py:mod:`@aws-cdk/cdk`) + This library includes the basic classes needed to write |cdk| stacks and apps. + + .. tabs:: + + .. group-tab:: C# + + Install the **Amazon.CDK NuGet** package: + + .. code-block:: sh + + dotnet add package Amazon.CDK + + .. group-tab:: JavaScript + + Install the **@aws-cdk/cdk** package: + + .. code-block:: sh + + npm install @aws-cdk/cdk + + .. group-tab:: TypeScript + + Install the **@aws-cdk/cdk** package: + + .. code-block:: sh + + npm install @aws-cdk/cdk + + .. group-tab:: Java + + Add the following to your project's `pom.xml` file: + + .. code-block:: xml + + + + software.amazon.awscdk + cdk + + + + + .. _define_app: + + Defining the |cdk| App + ---------------------- + + |cdk| apps are classes that extend the :py:class:`App <@aws-cdk/cdk.App>` + class. Create an empty **App**: + + .. tabs:: + + .. group-tab:: C# + + In **Program.cs** + + .. code-block:: c# + + using Amazon.CDK; + + namespace HelloCdk + { + class Program + { + static void Main(string[] args) + { + var myApp = new App(); + myApp.Run(); + } + } + } + + .. group-tab:: JavaScript + + Create the file **bin/hello-cdk.js**: + + .. code-block:: js + + const cdk = require('@aws-cdk/cdk'); + + class MyApp extends cdk.App { + constructor() { + super(); + } + } + + new MyApp().run(); + + .. group-tab:: TypeScript + + Create the file **bin/hello-cdk.ts**: + + .. code-block:: ts + + import cdk = require('@aws-cdk/cdk'); + import { HelloCdkStack } from '../lib/hello-cdkstack'; + + const app = new cdk.App(); + new HelloCdkStack(app, 'HelloCdkStack'); + app.run(); + + Create the file **lib/hello-cdkstack.ts**: + + .. code-block:: ts + + import cdk = require('@aws-cdk/cdk'); + + export class HelloCdkStack extends cdk.Stack { + constructor(parent: cdk.App, name: string, props?: cdk.StackProps) { + super(parent, name, props); + + // The code that defines your stack goes here + } + } + + .. group-tab:: Java + + In **src/main/java/com/acme/MyApp.java**: + + .. code-block:: java + + package com.acme; + + import software.amazon.awscdk.App; + + import java.util.Arrays; + + public class MyApp { + public static void main(final String argv[]) { + App app = new App(); + + app.run(); + } + } + + .. _compile_code: + + Compiling the Code + ------------------ + + If needed, compile the code: + + .. tabs:: + + .. group-tab:: C# + + Compile the code using your IDE or via the dotnet CLI: + + .. code-block:: sh + + dotnet build + + .. 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 + + Compile your code using your IDE or via the command line via **mvn**: + + .. code-block:: sh + + mvn compile + + You have now created your first |cdk| app. .. _list_stacks: From f4d57208aceb4ea163c10dc2d835bacdaab74c68 Mon Sep 17 00:00:00 2001 From: Doug-AWS Date: Thu, 6 Dec 2018 13:51:08 -0800 Subject: [PATCH 05/10] Fixed some build issues; minimized template/manual tabs: --- docs/src/apples_example.rst | 2 - docs/src/aws-construct-lib.rst | 32 +-- docs/src/getting-started.rst | 2 +- docs/src/passing-in-data.rst | 14 +- docs/src/tutorial.rst | 380 +-------------------------------- 5 files changed, 28 insertions(+), 402 deletions(-) diff --git a/docs/src/apples_example.rst b/docs/src/apples_example.rst index 91294b154bacd..fe5ef294f4d6a 100644 --- a/docs/src/apples_example.rst +++ b/docs/src/apples_example.rst @@ -65,14 +65,12 @@ so for now change it to the following: .. code-block:: ts - #!/usr/bin/env node import cdk = require('@aws-cdk/cdk'); class MyWidgetServiceStack extends cdk.Stack { constructor(parent: cdk.App, name: string, props?: cdk.StackProps) { super(parent, name, props); - } } diff --git a/docs/src/aws-construct-lib.rst b/docs/src/aws-construct-lib.rst index 4f71791a92c3f..8a8c41770c2e7 100644 --- a/docs/src/aws-construct-lib.rst +++ b/docs/src/aws-construct-lib.rst @@ -329,21 +329,23 @@ Synthesizes to: .. code-block:: json - "MyBucketF68F3FF0": { - "Type": "AWS::S3::Bucket", - "Properties": { - "BucketEncryption": { - "ServerSideEncryptionConfiguration": [ - { - "EncryptEverythingAndAlways": true - } - ] - }, - "VersioningConfiguration": { - "Status": "Enabled" - } - } - } + { + "MyBucketF68F3FF0": { + "Type": "AWS::S3::Bucket", + "Properties": { + "BucketEncryption": { + "ServerSideEncryptionConfiguration": [ + { + "EncryptEverythingAndAlways": true + } + ] + }, + "VersioningConfiguration": { + "Status": "Enabled" + } + } + } + } Directly Defining CloudFormation Resources ------------------------------------------- diff --git a/docs/src/getting-started.rst b/docs/src/getting-started.rst index e316be102030b..211f670613e4e 100644 --- a/docs/src/getting-started.rst +++ b/docs/src/getting-started.rst @@ -60,7 +60,7 @@ Run the following command to see the currently installed version of the toolkit cdk --version -.. _configuring_cdk: +.. _credentials: Configuring the |cdk| ===================== diff --git a/docs/src/passing-in-data.rst b/docs/src/passing-in-data.rst index 172325d35e369..074cffc6d1a32 100644 --- a/docs/src/passing-in-data.rst +++ b/docs/src/passing-in-data.rst @@ -253,12 +253,14 @@ where **S3Bucket** is the logical ID of the bucket in your template: .. code-block:: json - "S3Bucket": { - "Type": "AWS::S3::Bucket", - "Properties": { - ... - } - } + { + "S3Bucket": { + "Type": "AWS::S3::Bucket", + "Properties": { + ... + } + } + } You can include this bucket in your |cdk| app, as shown in the following example diff --git a/docs/src/tutorial.rst b/docs/src/tutorial.rst index baebd38e23d8c..0d406f2f0f3b0 100644 --- a/docs/src/tutorial.rst +++ b/docs/src/tutorial.rst @@ -32,388 +32,12 @@ All of these instructions use this directory: .. tab:: template - .. _cdk_init_project: - - Creating a Project from the Template - ==================================== - - In this section we use the :code:`cdk init` command to create a skeleton project from a - template in any of the supported languages. - - .. _initialize: - - Initializing the Project - ------------------------ - - Run the `cdk init` command to initialize an empty project. - The |cdk| contains templates for all of the supported languages. - To create an empty (no AWS resources in the resulting |CFN| stack), - run the following command, where LANGUAGE is one of the supported programming languages: - **csharp** (C#), **java** (Java), or **typescript** (TypeScript). - - .. code-block:: sh - - cdk init --language LANGUAGE - - .. _compile_project: - - Compiling the Project - --------------------- - - If needed, compile the code: - - .. tabs:: - - .. group-tab:: C# - - Compile the code using your IDE or via the dotnet CLI: - - .. code-block:: sh - - dotnet build - - .. 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 - - Compile your code using your IDE or via the command line via **mvn**: - - .. code-block:: sh - - mvn compile - - You have now created your first |cdk| app. + This is a template .. tab:: manual - .. _manual_project: - - Manually Creating a Project - =========================== - - In this section we create a new |cdk| project using explicit command-line commands. - Be sure to navigate to the *hello-cdk* directory before you start. - - .. _initializing_manually: - - Initializing the Project - ------------------------ - - Create an empty project for the |cdk| app. - - .. tabs:: - - .. group-tab:: C# - - Create a new console application. - - .. code-block:: sh - - dotnet new console - - .. group-tab:: JavaScript - - Create an initial npm **package.json** file: - - .. code-block:: sh - - npm init -y # creates package.json - - Create a **.gitignore** file with the following content: - - .. code-block:: sh - - *.js - node_modules - - .. group-tab:: TypeScript - - Create an initial npm **package.json** file: - - .. code-block:: sh - - npm init -y # creates package.json - - Create a **.gitignore** file with the following content: - - .. code-block:: sh - - *.js - *.d.ts - node_modules - - Add the `build` and `watch` TypeScript commands to **package.json**: - - .. code-block:: json - - { - "scripts": { - "build": "tsc", - "watch": "tsc -w" - } - } - - Create a minimal **tsconfig.json**: - - .. code-block:: json - - { - "compilerOptions": { - "target": "es2018", - "module": "commonjs" - } - } - - Create a minimal **cdk.json** (this saves you from including `--app node bin/hello-cdk.js` in every `cdk` command): - - .. code-block:: json - - { - "app": "node bin/hello-cdk.js" - } - - .. group-tab:: Java - - Create a **.gitignore** file with the following content: - - .. code-block:: sh - - .classpath.txt - target - .classpath - .project - .idea - .settings - .vscode - *.iml - - 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_core: - - Adding the CDK Core as a Dependency - ----------------------------------- - - Install the |cdk| core library (:py:mod:`@aws-cdk/cdk`) - This library includes the basic classes needed to write |cdk| stacks and apps. + This is manual - .. tabs:: - - .. group-tab:: C# - - Install the **Amazon.CDK NuGet** package: - - .. code-block:: sh - - dotnet add package Amazon.CDK - - .. group-tab:: JavaScript - - Install the **@aws-cdk/cdk** package: - - .. code-block:: sh - - npm install @aws-cdk/cdk - - .. group-tab:: TypeScript - - Install the **@aws-cdk/cdk** package: - - .. code-block:: sh - - npm install @aws-cdk/cdk - - .. group-tab:: Java - - Add the following to your project's `pom.xml` file: - - .. code-block:: xml - - - - software.amazon.awscdk - cdk - - - - - .. _define_app: - - Defining the |cdk| App - ---------------------- - - |cdk| apps are classes that extend the :py:class:`App <@aws-cdk/cdk.App>` - class. Create an empty **App**: - - .. tabs:: - - .. group-tab:: C# - - In **Program.cs** - - .. code-block:: c# - - using Amazon.CDK; - - namespace HelloCdk - { - class Program - { - static void Main(string[] args) - { - var myApp = new App(); - myApp.Run(); - } - } - } - - .. group-tab:: JavaScript - - Create the file **bin/hello-cdk.js**: - - .. code-block:: js - - const cdk = require('@aws-cdk/cdk'); - - class MyApp extends cdk.App { - constructor() { - super(); - } - } - - new MyApp().run(); - - .. group-tab:: TypeScript - - Create the file **bin/hello-cdk.ts**: - - .. code-block:: ts - - import cdk = require('@aws-cdk/cdk'); - import { HelloCdkStack } from '../lib/hello-cdkstack'; - - const app = new cdk.App(); - new HelloCdkStack(app, 'HelloCdkStack'); - app.run(); - - Create the file **lib/hello-cdkstack.ts**: - - .. code-block:: ts - - import cdk = require('@aws-cdk/cdk'); - - export class HelloCdkStack extends cdk.Stack { - constructor(parent: cdk.App, name: string, props?: cdk.StackProps) { - super(parent, name, props); - - // The code that defines your stack goes here - } - } - - .. group-tab:: Java - - In **src/main/java/com/acme/MyApp.java**: - - .. code-block:: java - - package com.acme; - - import software.amazon.awscdk.App; - - import java.util.Arrays; - - public class MyApp { - public static void main(final String argv[]) { - App app = new App(); - - app.run(); - } - } - - .. _compile_code: - - Compiling the Code - ------------------ - - If needed, compile the code: - - .. tabs:: - - .. group-tab:: C# - - Compile the code using your IDE or via the dotnet CLI: - - .. code-block:: sh - - dotnet build - - .. 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 - - Compile your code using your IDE or via the command line via **mvn**: - - .. code-block:: sh - - mvn compile - - You have now created your first |cdk| app. - .. _list_stacks: Listing the Stacks in the App From b0c38c58e79086e3d59c374ee8827a854dfdc655 Mon Sep 17 00:00:00 2001 From: Doug-AWS Date: Thu, 6 Dec 2018 13:55:35 -0800 Subject: [PATCH 06/10] Added pseudo-value to S3 bucket properties in JSON --- docs/src/passing-in-data.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/passing-in-data.rst b/docs/src/passing-in-data.rst index 074cffc6d1a32..5f146e8a74a36 100644 --- a/docs/src/passing-in-data.rst +++ b/docs/src/passing-in-data.rst @@ -257,7 +257,7 @@ where **S3Bucket** is the logical ID of the bucket in your template: "S3Bucket": { "Type": "AWS::S3::Bucket", "Properties": { - ... + "prop1": "value1" } } } From ab09ebacc69d6be9bd8bc4c52bfb9baf2c12d157 Mon Sep 17 00:00:00 2001 From: Doug-AWS Date: Thu, 6 Dec 2018 14:11:09 -0800 Subject: [PATCH 07/10] Removed headings from template.txt and manual.txt --- docs/src/manual.txt | 604 ++++++++++++++++++++---------------------- docs/src/template.txt | 130 +++++---- docs/src/tutorial.rst | 6 +- 3 files changed, 357 insertions(+), 383 deletions(-) diff --git a/docs/src/manual.txt b/docs/src/manual.txt index 4853c3957c1f6..cdaeb254ff9e7 100644 --- a/docs/src/manual.txt +++ b/docs/src/manual.txt @@ -1,310 +1,294 @@ - - .. _manual_project: - - Manually Creating a Project - =========================== - - In this section we create a new |cdk| project using explicit command-line commands. - Be sure to navigate to the *hello-cdk* directory before you start. - - .. _initializing_manually: - - Initializing the Project - ------------------------ - - Create an empty project for the |cdk| app. - - .. tabs:: - - .. group-tab:: C# - - Create a new console application. - - .. code-block:: sh - - dotnet new console - - .. group-tab:: JavaScript - - Create an initial npm **package.json** file: - - .. code-block:: sh - - npm init -y # creates package.json - - Create a **.gitignore** file with the following content: - - .. code-block:: sh - - *.js - node_modules - - .. group-tab:: TypeScript - - Create an initial npm **package.json** file: - - .. code-block:: sh - - npm init -y # creates package.json - - Create a **.gitignore** file with the following content: - - .. code-block:: sh - - *.js - *.d.ts - node_modules - - Add the `build` and `watch` TypeScript commands to **package.json**: - - .. code-block:: json - - { - "scripts": { - "build": "tsc", - "watch": "tsc -w" - } - } - - Create a minimal **tsconfig.json**: - - .. code-block:: json - - { - "compilerOptions": { - "target": "es2018", - "module": "commonjs" - } - } - - Create a minimal **cdk.json** (this saves you from including `--app node bin/hello-cdk.js` in every `cdk` command): - - .. code-block:: json - - { - "app": "node bin/hello-cdk.js" - } - - .. group-tab:: Java - - Create a **.gitignore** file with the following content: - - .. code-block:: sh - - .classpath.txt - target - .classpath - .project - .idea - .settings - .vscode - *.iml - - 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_core: - - Adding the CDK Core as a Dependency - ----------------------------------- - - Install the |cdk| core library (:py:mod:`@aws-cdk/cdk`) - This library includes the basic classes needed to write |cdk| stacks and apps. - - .. tabs:: - - .. group-tab:: C# - - Install the **Amazon.CDK NuGet** package: - - .. code-block:: sh - - dotnet add package Amazon.CDK - - .. group-tab:: JavaScript - - Install the **@aws-cdk/cdk** package: - - .. code-block:: sh - - npm install @aws-cdk/cdk - - .. group-tab:: TypeScript - - Install the **@aws-cdk/cdk** package: - - .. code-block:: sh - - npm install @aws-cdk/cdk - - .. group-tab:: Java - - Add the following to your project's `pom.xml` file: - - .. code-block:: xml - - - - software.amazon.awscdk - cdk - - - - - .. _define_app: - - Defining the |cdk| App - ---------------------- - - |cdk| apps are classes that extend the :py:class:`App <@aws-cdk/cdk.App>` - class. Create an empty **App**: - - .. tabs:: - - .. group-tab:: C# - - In **Program.cs** - - .. code-block:: c# - - using Amazon.CDK; - - namespace HelloCdk - { - class Program - { - static void Main(string[] args) - { - var myApp = new App(); - myApp.Run(); - } - } - } - - .. group-tab:: JavaScript - - Create the file **bin/hello-cdk.js**: - - .. code-block:: js - - const cdk = require('@aws-cdk/cdk'); - - class MyApp extends cdk.App { - constructor() { - super(); - } - } - - new MyApp().run(); - - .. group-tab:: TypeScript - - Create the file **bin/hello-cdk.ts**: - - .. code-block:: ts - - import cdk = require('@aws-cdk/cdk'); - import { HelloCdkStack } from '../lib/hello-cdkstack'; - - const app = new cdk.App(); - new HelloCdkStack(app, 'HelloCdkStack'); - app.run(); - - Create the file **lib/hello-cdkstack.ts**: - - .. code-block:: ts - - import cdk = require('@aws-cdk/cdk'); - - export class HelloCdkStack extends cdk.Stack { - constructor(parent: cdk.App, name: string, props?: cdk.StackProps) { - super(parent, name, props); - - // The code that defines your stack goes here - } - } - - .. group-tab:: Java - - In **src/main/java/com/acme/MyApp.java**: - - .. code-block:: java - - package com.acme; - - import software.amazon.awscdk.App; - - import java.util.Arrays; - - public class MyApp { - public static void main(final String argv[]) { - App app = new App(); - - app.run(); - } - } - - .. _compile_code: - - Compiling the Code - ------------------ - - If needed, compile the code: - - .. tabs:: - - .. group-tab:: C# - - Compile the code using your IDE or via the dotnet CLI: - - .. code-block:: sh - - dotnet build - - .. 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 - - Compile your code using your IDE or via the command line via **mvn**: - - .. code-block:: sh - - mvn compile - - You have now created your first |cdk| app. + **Manually Creating a Project** + + In this section we create a new |cdk| project using explicit command-line commands. + Be sure to navigate to the *hello-cdk* directory before you start. + + **Initializing the Project** + + Create an empty project for the |cdk| app. + + .. tabs:: + + .. group-tab:: C# + + Create a new console application. + + .. code-block:: sh + + dotnet new console + + .. group-tab:: JavaScript + + Create an initial npm **package.json** file: + + .. code-block:: sh + + npm init -y # creates package.json + + Create a **.gitignore** file with the following content: + + .. code-block:: sh + + *.js + node_modules + + .. group-tab:: TypeScript + + Create an initial npm **package.json** file: + + .. code-block:: sh + + npm init -y # creates package.json + + Create a **.gitignore** file with the following content: + + .. code-block:: sh + + *.js + *.d.ts + node_modules + + Add the `build` and `watch` TypeScript commands to **package.json**: + + .. code-block:: json + + { + "scripts": { + "build": "tsc", + "watch": "tsc -w" + } + } + + Create a minimal **tsconfig.json**: + + .. code-block:: json + + { + "compilerOptions": { + "target": "es2018", + "module": "commonjs" + } + } + + Create a minimal **cdk.json** (this saves you from including `--app node bin/hello-cdk.js` in every `cdk` command): + + .. code-block:: json + + { + "app": "node bin/hello-cdk.js" + } + + .. group-tab:: Java + + Create a **.gitignore** file with the following content: + + .. code-block:: sh + + .classpath.txt + target + .classpath + .project + .idea + .settings + .vscode + *.iml + + 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 + + + + + + **Adding the CDK Core as a Dependency** + + Install the |cdk| core library (:py:mod:`@aws-cdk/cdk`) + This library includes the basic classes needed to write |cdk| stacks and apps. + + .. tabs:: + + .. group-tab:: C# + + Install the **Amazon.CDK NuGet** package: + + .. code-block:: sh + + dotnet add package Amazon.CDK + + .. group-tab:: JavaScript + + Install the **@aws-cdk/cdk** package: + + .. code-block:: sh + + npm install @aws-cdk/cdk + + .. group-tab:: TypeScript + + Install the **@aws-cdk/cdk** package: + + .. code-block:: sh + + npm install @aws-cdk/cdk + + .. group-tab:: Java + + Add the following to your project's `pom.xml` file: + + .. code-block:: xml + + + + software.amazon.awscdk + cdk + + + + + **Defining the |cdk| App** + + |cdk| apps are classes that extend the :py:class:`App <@aws-cdk/cdk.App>` + class. Create an empty **App**: + + .. tabs:: + + .. group-tab:: C# + + In **Program.cs** + + .. code-block:: c# + + using Amazon.CDK; + + namespace HelloCdk + { + class Program + { + static void Main(string[] args) + { + var myApp = new App(); + myApp.Run(); + } + } + } + + .. group-tab:: JavaScript + + Create the file **bin/hello-cdk.js**: + + .. code-block:: js + + const cdk = require('@aws-cdk/cdk'); + + class MyApp extends cdk.App { + constructor() { + super(); + } + } + + new MyApp().run(); + + .. group-tab:: TypeScript + + Create the file **bin/hello-cdk.ts**: + + .. code-block:: ts + + import cdk = require('@aws-cdk/cdk'); + import { HelloCdkStack } from '../lib/hello-cdkstack'; + + const app = new cdk.App(); + new HelloCdkStack(app, 'HelloCdkStack'); + app.run(); + + Create the file **lib/hello-cdkstack.ts**: + + .. code-block:: ts + + import cdk = require('@aws-cdk/cdk'); + + export class HelloCdkStack extends cdk.Stack { + constructor(parent: cdk.App, name: string, props?: cdk.StackProps) { + super(parent, name, props); + + // The code that defines your stack goes here + } + } + + .. group-tab:: Java + + In **src/main/java/com/acme/MyApp.java**: + + .. code-block:: java + + package com.acme; + + import software.amazon.awscdk.App; + + import java.util.Arrays; + + public class MyApp { + public static void main(final String argv[]) { + App app = new App(); + + app.run(); + } + } + + **Compiling the Code** + + If needed, compile the code: + + .. tabs:: + + .. group-tab:: C# + + Compile the code using your IDE or via the dotnet CLI: + + .. code-block:: sh + + dotnet build + + .. 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 + + Compile your code using your IDE or via the command line via **mvn**: + + .. code-block:: sh + + mvn compile + + You have now created your first |cdk| app. diff --git a/docs/src/template.txt b/docs/src/template.txt index 9ca976f8b834c..302361725c48d 100644 --- a/docs/src/template.txt +++ b/docs/src/template.txt @@ -1,70 +1,60 @@ - - .. _cdk_init_project: - - Creating a Project from the Template - ==================================== - - In this section we use the :code:`cdk init` command to create a skeleton project from a - template in any of the supported languages. - - .. _initialize: - - Initializing the Project - ------------------------ - - Run the `cdk init` command to initialize an empty project. - The |cdk| contains templates for all of the supported languages. - To create an empty (no AWS resources in the resulting |CFN| stack), - run the following command, where LANGUAGE is one of the supported programming languages: - **csharp** (C#), **java** (Java), or **typescript** (TypeScript). - - .. code-block:: sh - - cdk init --language LANGUAGE - - .. _compile_project: - - Compiling the Project - --------------------- - - If needed, compile the code: - - .. tabs:: - - .. group-tab:: C# - - Compile the code using your IDE or via the dotnet CLI: - - .. code-block:: sh - - dotnet build - - .. 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 - - Compile your code using your IDE or via the command line via **mvn**: - - .. code-block:: sh - - mvn compile - - You have now created your first |cdk| app. + **Creating a Project from the Template** + + In this section we use the :code:`cdk init` command to create a skeleton project from a + template in any of the supported languages. + + **Initializing the Project** + + Run the `cdk init` command to initialize an empty project. + The |cdk| contains templates for all of the supported languages. + To create an empty (no AWS resources in the resulting |CFN| stack), + run the following command, where LANGUAGE is one of the supported programming languages: + **csharp** (C#), **java** (Java), or **typescript** (TypeScript). + + .. code-block:: sh + + cdk init --language LANGUAGE + + **Compiling the Project** + + If needed, compile the code: + + .. tabs:: + + .. group-tab:: C# + + Compile the code using your IDE or via the dotnet CLI: + + .. code-block:: sh + + dotnet build + + .. 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 + + Compile your code using your IDE or via the command line via **mvn**: + + .. code-block:: sh + + mvn compile + + You have now created your first |cdk| app. diff --git a/docs/src/tutorial.rst b/docs/src/tutorial.rst index 0d406f2f0f3b0..c82eb28556d84 100644 --- a/docs/src/tutorial.rst +++ b/docs/src/tutorial.rst @@ -30,13 +30,13 @@ All of these instructions use this directory: .. tabs:: - .. tab:: template + .. tab:: template - This is a template + .. include:: template.txt .. tab:: manual - This is manual + .. include:: manual.txt .. _list_stacks: From 96f117e477aec384be27bb3dc74c3bd7e2837724 Mon Sep 17 00:00:00 2001 From: Doug-AWS Date: Thu, 6 Dec 2018 14:38:32 -0800 Subject: [PATCH 08/10] Cannot nest tabs --- docs/src/manual.txt | 294 ------------------------------- docs/src/template.txt | 60 ------- docs/src/tutorial.rst | 389 +++++++++++++++++++++++++++++++++++++++++- 3 files changed, 382 insertions(+), 361 deletions(-) delete mode 100644 docs/src/manual.txt delete mode 100644 docs/src/template.txt diff --git a/docs/src/manual.txt b/docs/src/manual.txt deleted file mode 100644 index cdaeb254ff9e7..0000000000000 --- a/docs/src/manual.txt +++ /dev/null @@ -1,294 +0,0 @@ - **Manually Creating a Project** - - In this section we create a new |cdk| project using explicit command-line commands. - Be sure to navigate to the *hello-cdk* directory before you start. - - **Initializing the Project** - - Create an empty project for the |cdk| app. - - .. tabs:: - - .. group-tab:: C# - - Create a new console application. - - .. code-block:: sh - - dotnet new console - - .. group-tab:: JavaScript - - Create an initial npm **package.json** file: - - .. code-block:: sh - - npm init -y # creates package.json - - Create a **.gitignore** file with the following content: - - .. code-block:: sh - - *.js - node_modules - - .. group-tab:: TypeScript - - Create an initial npm **package.json** file: - - .. code-block:: sh - - npm init -y # creates package.json - - Create a **.gitignore** file with the following content: - - .. code-block:: sh - - *.js - *.d.ts - node_modules - - Add the `build` and `watch` TypeScript commands to **package.json**: - - .. code-block:: json - - { - "scripts": { - "build": "tsc", - "watch": "tsc -w" - } - } - - Create a minimal **tsconfig.json**: - - .. code-block:: json - - { - "compilerOptions": { - "target": "es2018", - "module": "commonjs" - } - } - - Create a minimal **cdk.json** (this saves you from including `--app node bin/hello-cdk.js` in every `cdk` command): - - .. code-block:: json - - { - "app": "node bin/hello-cdk.js" - } - - .. group-tab:: Java - - Create a **.gitignore** file with the following content: - - .. code-block:: sh - - .classpath.txt - target - .classpath - .project - .idea - .settings - .vscode - *.iml - - 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 - - - - - - **Adding the CDK Core as a Dependency** - - Install the |cdk| core library (:py:mod:`@aws-cdk/cdk`) - This library includes the basic classes needed to write |cdk| stacks and apps. - - .. tabs:: - - .. group-tab:: C# - - Install the **Amazon.CDK NuGet** package: - - .. code-block:: sh - - dotnet add package Amazon.CDK - - .. group-tab:: JavaScript - - Install the **@aws-cdk/cdk** package: - - .. code-block:: sh - - npm install @aws-cdk/cdk - - .. group-tab:: TypeScript - - Install the **@aws-cdk/cdk** package: - - .. code-block:: sh - - npm install @aws-cdk/cdk - - .. group-tab:: Java - - Add the following to your project's `pom.xml` file: - - .. code-block:: xml - - - - software.amazon.awscdk - cdk - - - - - **Defining the |cdk| App** - - |cdk| apps are classes that extend the :py:class:`App <@aws-cdk/cdk.App>` - class. Create an empty **App**: - - .. tabs:: - - .. group-tab:: C# - - In **Program.cs** - - .. code-block:: c# - - using Amazon.CDK; - - namespace HelloCdk - { - class Program - { - static void Main(string[] args) - { - var myApp = new App(); - myApp.Run(); - } - } - } - - .. group-tab:: JavaScript - - Create the file **bin/hello-cdk.js**: - - .. code-block:: js - - const cdk = require('@aws-cdk/cdk'); - - class MyApp extends cdk.App { - constructor() { - super(); - } - } - - new MyApp().run(); - - .. group-tab:: TypeScript - - Create the file **bin/hello-cdk.ts**: - - .. code-block:: ts - - import cdk = require('@aws-cdk/cdk'); - import { HelloCdkStack } from '../lib/hello-cdkstack'; - - const app = new cdk.App(); - new HelloCdkStack(app, 'HelloCdkStack'); - app.run(); - - Create the file **lib/hello-cdkstack.ts**: - - .. code-block:: ts - - import cdk = require('@aws-cdk/cdk'); - - export class HelloCdkStack extends cdk.Stack { - constructor(parent: cdk.App, name: string, props?: cdk.StackProps) { - super(parent, name, props); - - // The code that defines your stack goes here - } - } - - .. group-tab:: Java - - In **src/main/java/com/acme/MyApp.java**: - - .. code-block:: java - - package com.acme; - - import software.amazon.awscdk.App; - - import java.util.Arrays; - - public class MyApp { - public static void main(final String argv[]) { - App app = new App(); - - app.run(); - } - } - - **Compiling the Code** - - If needed, compile the code: - - .. tabs:: - - .. group-tab:: C# - - Compile the code using your IDE or via the dotnet CLI: - - .. code-block:: sh - - dotnet build - - .. 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 - - Compile your code using your IDE or via the command line via **mvn**: - - .. code-block:: sh - - mvn compile - - You have now created your first |cdk| app. diff --git a/docs/src/template.txt b/docs/src/template.txt deleted file mode 100644 index 302361725c48d..0000000000000 --- a/docs/src/template.txt +++ /dev/null @@ -1,60 +0,0 @@ - **Creating a Project from the Template** - - In this section we use the :code:`cdk init` command to create a skeleton project from a - template in any of the supported languages. - - **Initializing the Project** - - Run the `cdk init` command to initialize an empty project. - The |cdk| contains templates for all of the supported languages. - To create an empty (no AWS resources in the resulting |CFN| stack), - run the following command, where LANGUAGE is one of the supported programming languages: - **csharp** (C#), **java** (Java), or **typescript** (TypeScript). - - .. code-block:: sh - - cdk init --language LANGUAGE - - **Compiling the Project** - - If needed, compile the code: - - .. tabs:: - - .. group-tab:: C# - - Compile the code using your IDE or via the dotnet CLI: - - .. code-block:: sh - - dotnet build - - .. 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 - - Compile your code using your IDE or via the command line via **mvn**: - - .. code-block:: sh - - mvn compile - - You have now created your first |cdk| app. diff --git a/docs/src/tutorial.rst b/docs/src/tutorial.rst index c82eb28556d84..aca82b216f380 100644 --- a/docs/src/tutorial.rst +++ b/docs/src/tutorial.rst @@ -15,8 +15,10 @@ Tutorial: Creating an |cdk| Application ####################################### This topic walks you through creating and deploying an |cdk| app, -by using the `cdk init` command, as described in the **Template** tab, -or manually, as described in the **Manual** tab. +by using the `cdk init` command, as described in the +`Creating a Project from the Template`_ section, +or manually, as described in the +`Creating a Project Manually`_ section. In either case, the first step is to create the directory for your project, with an empty Git repository. @@ -28,15 +30,388 @@ All of these instructions use this directory: cd hello-cdk git init +.. _template_create_project: + +Creating a Project from the Template +==================================== + +In this section we use the :code:`cdk init` command to create a skeleton project from a +template in any of the supported languages. + +.. _template_initialize: + +Initializing the Project +------------------------ + +Run the `cdk init` command to initialize an empty project. +The |cdk| contains templates for all of the supported languages. +To create an empty (no AWS resources in the resulting |CFN| stack), +run the following command, where LANGUAGE is one of the supported programming languages: +**csharp** (C#), **java** (Java), or **typescript** (TypeScript). + +.. code-block:: sh + + cdk init --language LANGUAGE + +.. _template_compile: + +Compiling the Project +--------------------- + +If needed, compile the code: + .. tabs:: - .. tab:: template - - .. include:: template.txt + .. group-tab:: C# + + Compile the code using your IDE or via the dotnet CLI: + + .. code-block:: sh + + dotnet build + + .. 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 + + Compile your code using your IDE or via the command line via **mvn**: + + .. code-block:: sh + + mvn compile + +You have now created your first |cdk| app. +The next section creates a similar app manually, +so you can skip it and continue with the +`Listing the Stacks in the App`_ section. + +.. _manual_create_project: + +Manually Creating a Project +=========================== + +In this section we create a new |cdk| project using explicit command-line commands. +Be sure to navigate to the *hello-cdk* directory before you start. + +.. _manual_initialize: + +Initializing the Project +------------------------ + +Create an empty project for the |cdk| app. + +.. tabs:: + + .. group-tab:: C# + + Create a new console application. + + .. code-block:: sh + + dotnet new console + + .. group-tab:: JavaScript + + Create an initial npm **package.json** file: + + .. code-block:: sh + + npm init -y # creates package.json + + Create a **.gitignore** file with the following content: + + .. code-block:: sh + + *.js + node_modules + + .. group-tab:: TypeScript + + Create an initial npm **package.json** file: + + .. code-block:: sh + + npm init -y # creates package.json + + Create a **.gitignore** file with the following content: + + .. code-block:: sh + + *.js + *.d.ts + node_modules + + Add the `build` and `watch` TypeScript commands to **package.json**: + + .. code-block:: json + + { + "scripts": { + "build": "tsc", + "watch": "tsc -w" + } + } + + Create a minimal **tsconfig.json**: + + .. code-block:: json + + { + "compilerOptions": { + "target": "es2018", + "module": "commonjs" + } + } + + Create a minimal **cdk.json** (this saves you from including `--app node bin/hello-cdk.js` in every `cdk` command): + + .. code-block:: json + + { + "app": "node bin/hello-cdk.js" + } + + .. group-tab:: Java + + Create a **.gitignore** file with the following content: + + .. code-block:: sh + + .classpath.txt + target + .classpath + .project + .idea + .settings + .vscode + *.iml + + 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 + + + + + +.. _manual_add_core: + +Adding the CDK Core as a Dependency +----------------------------------- + +Install the |cdk| core library (:py:mod:`@aws-cdk/cdk`) +This library includes the basic classes needed to write |cdk| stacks and apps. + +.. tabs:: + + .. group-tab:: C# + + Install the **Amazon.CDK NuGet** package: + + .. code-block:: sh + + dotnet add package Amazon.CDK + + .. group-tab:: JavaScript + + Install the **@aws-cdk/cdk** package: + + .. code-block:: sh + + npm install @aws-cdk/cdk - .. tab:: manual + .. group-tab:: TypeScript + + Install the **@aws-cdk/cdk** package: + + .. code-block:: sh + + npm install @aws-cdk/cdk + + .. group-tab:: Java + + Add the following to your project's `pom.xml` file: + + .. code-block:: xml + + + + software.amazon.awscdk + cdk + + + + +.. _manual_define_app: + +Defining the |cdk| App +---------------------- + +|cdk| apps are classes that extend the :py:class:`App <@aws-cdk/cdk.App>` +class. Create an empty **App**: + +.. tabs:: + + .. group-tab:: C# + + In **Program.cs** + + .. code-block:: c# + + using Amazon.CDK; + + namespace HelloCdk + { + class Program + { + static void Main(string[] args) + { + var myApp = new App(); + myApp.Run(); + } + } + } + + .. group-tab:: JavaScript + + Create the file **bin/hello-cdk.js**: + + .. code-block:: js + + const cdk = require('@aws-cdk/cdk'); + + class MyApp extends cdk.App { + constructor() { + super(); + } + } + + new MyApp().run(); + + .. group-tab:: TypeScript + + Create the file **bin/hello-cdk.ts**: + + .. code-block:: ts + + import cdk = require('@aws-cdk/cdk'); + import { HelloCdkStack } from '../lib/hello-cdkstack'; + + const app = new cdk.App(); + new HelloCdkStack(app, 'HelloCdkStack'); + app.run(); + + Create the file **lib/hello-cdkstack.ts**: + + .. code-block:: ts + + import cdk = require('@aws-cdk/cdk'); + + export class HelloCdkStack extends cdk.Stack { + constructor(parent: cdk.App, name: string, props?: cdk.StackProps) { + super(parent, name, props); + + // The code that defines your stack goes here + } + } + + .. group-tab:: Java + + In **src/main/java/com/acme/MyApp.java**: + + .. code-block:: java + + package com.acme; + + import software.amazon.awscdk.App; + + import java.util.Arrays; + + public class MyApp { + public static void main(final String argv[]) { + App app = new App(); + + app.run(); + } + } + +.. _manual_compile: + +Compiling the Code +------------------ + +If needed, compile the code: + +.. tabs:: + + .. group-tab:: C# + + Compile the code using your IDE or via the dotnet CLI: + + .. code-block:: sh + + dotnet build + + .. 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 + + Compile your code using your IDE or via the command line via **mvn**: + + .. code-block:: sh + + mvn compile - .. include:: manual.txt +You have now created your first |cdk| app. .. _list_stacks: From 146558dfe6fbdc810d5048674982682a8dbe35f4 Mon Sep 17 00:00:00 2001 From: Doug-AWS Date: Thu, 6 Dec 2018 14:44:18 -0800 Subject: [PATCH 09/10] Fixed bad link --- docs/src/tutorial.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/tutorial.rst b/docs/src/tutorial.rst index aca82b216f380..39befa9b408b1 100644 --- a/docs/src/tutorial.rst +++ b/docs/src/tutorial.rst @@ -105,7 +105,7 @@ so you can skip it and continue with the .. _manual_create_project: -Manually Creating a Project +Creating a Project Manually =========================== In this section we create a new |cdk| project using explicit command-line commands. From 2f46ee448668c31da1bbaeb76772da70950dae70 Mon Sep 17 00:00:00 2001 From: Doug-AWS Date: Fri, 7 Dec 2018 09:54:45 -0800 Subject: [PATCH 10/10] Updated apple service example --- docs/src/apples_example.rst | 62 ++++++++++++------------------------- 1 file changed, 19 insertions(+), 43 deletions(-) diff --git a/docs/src/apples_example.rst b/docs/src/apples_example.rst index fe5ef294f4d6a..fb78ea2ca987d 100644 --- a/docs/src/apples_example.rst +++ b/docs/src/apples_example.rst @@ -11,16 +11,14 @@ .. _apples_example: ############## - +Apples Example ############## This example walks you through creating the resources for a simple widget dispensing service. It includes: -* A |LAMlong| function - +* An |LAMlong| function * An |ABP| API to call our |LAM| function - * An |S3| bucket that contains our |LAM| function code .. _overview: @@ -59,30 +57,10 @@ Let's create the TypeScript app **MyWidgetService** in in the current folder. cd MyWidgetService cdk init --language typescript -This creates *my_widget_service.ts* in the *bin* directory. -We don't need most of this code, -so for now change it to the following: - -.. code-block:: ts - - import cdk = require('@aws-cdk/cdk'); - - class MyWidgetServiceStack extends cdk.Stack { - constructor(parent: cdk.App, name: string, props?: cdk.StackProps) { - super(parent, name, props); - - } - } - - // Create a new CDK app - const app = new cdk.App(); +This creates *my_widget_service.ts* in the *bin* directory +and *my_widget_service-stack.ts* in the *lib*. - // Add your stack to it - new MyWidgetServiceStack(app, 'MyWidgetServiceStack'); - - app.run(); - -Save it and make sure it builds and creates an empty stack. +Make sure it builds and creates an empty stack. .. code-block:: sh @@ -96,10 +74,9 @@ where CDK-VERSION is the version of the CDK. Resources: CDKMetadata: - Type: 'AWS::CDK::Metadata' + Type: AWS::CDK::Metadata Properties: - Modules: >- - @aws-cdk/cdk=CDK-VERSION,@aws-cdk/cx-api=CDK-VERSION,my_widget_service=0.1.0 + Modules: "@aws-cdk/cdk=CDK-VERSION,@aws-cdk/cx-api=CDK-VERSION,my_widget_service=0.1.0" .. _create_lambda_functions: @@ -179,13 +156,6 @@ Add the |ABP|, |LAM|, and |S3| packages to our app. npm install @aws-cdk/aws-apigateway @aws-cdk/aws-lambda @aws-cdk/aws-s3 -Create the directory *lib* at the same level as the *bin* and *resources* -directories. - -.. code-block:: sh - - mkdir lib - Create the following Typescript file, *widget_service.ts*, in the *lib* directory. @@ -244,21 +214,21 @@ Step 4: Add the Service to the App ================================== To add the service to our app, -add the following line of code after the existing **import** statement in -*my_widget_service.ts*. +we need to first modify *my_widget_service-stack.ts*. +Add the following line of code after the existing **import** statement. .. code-block:: ts import widget_service = require('../lib/widget_service'); -Add the following line of code at the end of the constructor in *my_widget_service.ts*. +Replace the comment in the constructor with the following line of code. .. code-block:: ts new widget_service.WidgetService(this, 'Widgets'); Make sure it builds and creates a stack -(we don't show the stack as it's almost 300 lines). +(we don't show the stack as it's over 250 lines). .. code-block:: sh @@ -274,7 +244,8 @@ Before you can deploy your first |cdk| app, you must bootstrap your deployment, which creates some AWS infracture that the |cdk| needs. -See the **bootstrap** section of the :doc:`tools` topic for details. +See the **bootstrap** section of the :doc:`tools` topic for details +(you'll get a warning and nothing changes if you may have done this already). .. code-block:: sh @@ -287,7 +258,7 @@ Run the following command to deploy your app. cdk deploy If the deployment is successfull, -save the URL for your server, which appears in the last line in the window, +save the URL for your server, which appears in one of the last lines in the window, where GUID is an alpha-numeric GUID and REGION is your region. .. code-block:: sh @@ -447,6 +418,11 @@ by adding the following code at the end of the constructor. Save, build, and deploy the app. +.. code-block:: sh + + npm run build + cdk deploy + Now we should be able to store, show, or delete an individual widget. Use the following **curl** commands to list the widgets, create the widget *dummy*,