AWS Cloud9
User Guide

AWS CDK Sample for AWS Cloud9

This sample shows you how to work with the AWS Cloud Development Kit (AWS CDK) in an AWS Cloud9 development environment. The AWS CDK is a set of software tools and libraries that developers can use to model AWS infrastructure components as code.

The AWS CDK includes the AWS Construct Library that you can use to quickly resolve many tasks on AWS. For example, you can use the Fleet construct to fully and securely deploy code to a fleet of hosts. You can create your own constructs to model various elements of your architectures, share them with others, or publish them to the community. For more information, see the AWS Cloud Development Kit User Guide.

The AWS CDK is currently in developer preview and we look forward to community feedback and collaboration!

Creating this sample might result in charges to your AWS account. These include possible charges for services such as Amazon EC2, Amazon SNS, and Amazon SQS. For more information, see Amazon EC2 Pricing, Amazon SNS Pricing, and Amazon SQS Pricing.

Prerequisites

Before you use this sample, be sure to meet the following requirements.

  • You must have an existing AWS Cloud9 development environment. This sample assumes you already have an AWS Cloud9 EC2 development environment that is connected to an Amazon EC2 instance running Amazon Linux. If you have a different type of environment or operating system, you might need to adapt this sample's instructions to set up related tools. See Creating an Environment for details.

  • You have the AWS Cloud IDE for the existing environment already open. When you open an environment, AWS Cloud9 opens the IDE for that environment in your web browser. See Opening an Environment for details.

Step 1: Install Required Tools

In this step, you install all of the tools in your environment that the AWS CDK needs to run a sample that is written in the TypeScript programming language:

  1. Node Version Manager, or nvm , which you use to install Node.js later.

  2. Node.js, which is required by the sample and contains Node Package Manager, or npm , which you use to install TypeScript and the AWS CDK later.

  3. TypeScript, which is required by this sample. (The AWS CDK also provides support for several other programming languages.)

  4. The AWS CDK.

Step 1.1: Install Node Version Manager (nvm)

  1. In a terminal session in the AWS Cloud9 IDE, ensure the latest security updates and bug fixes are installed. To do this, run the yum update command. (To start a new terminal session, on the menu bar, choose Window, New Terminal.)

    sudo yum -y update
  2. Confirm whether nvm is already installed. To do this, run the nvm command with the --version option.

    nvm --version

    If successful, the output contains the nvm version number, and you can skip ahead to Step 1.2: Install Node.js.

  3. Download and install nvm . To do this, run the following command.

    curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.0/install.sh | bash
  4. Start using nvm . You can either close the terminal session and then restart it, or source the ~/.bashrc file that contains the commands to load nvm .

    . ~/.bashrc

Step 1.2: Install Node.js

  1. Confirm whether you already have Node.js installed, and if you do, confirm that the installed version is 8.11.0 or greater. This sample has been tested with Node.js 8.11.0. To check, with the terminal session still open in the IDE, run the node command with the --version option.

    node --version

    If you do have Node.js installed, the output contains the version number. If the version number is v8.11.0, skip ahead to Step 1.3: Install TypeScript.

  2. Install Node.js 8.11.0 by running the nvm command with the install action and the version number, as follows.

    nvm install v8.11.0
  3. Start using Node.js 8.11.0. To do this, run the nvm command along with the alias action, the version number to alias, and the version to use for that alias, as follows.

    nvm alias default 8.11.0

    Note

    The preceding command sets Node.js 8.11.0 as the default version of Node.js. Alternatively, you can run the nvm command along with the use action instead of the alias action (for example, nvm use 8.11.0 ). However, the use action causes that version of Node.js to run only while the current terminal session is running.

  4. To confirm that you're using Node.js 8.11.0, run the node --version command again. If the correct version is installed, the output contains version v8.11.0.

Step 1.3: Install TypeScript

  1. Confirm whether you already have TypeScript installed. To do this, with the terminal session still open in the IDE, run the command-line TypeScript compiler with the --version option.

    tsc --version

    If you do have TypeScript installed, the output contains the TypeScript version number. If TypeScript is installed, skip ahead to Step 1.4: Install the AWS CDK.

  2. Install TypeScript. To do this, run the npm command with the install action, the -g option, and the name of the TypeScript package. This installs TypeScript as a global package in the environment.

    npm install -g typescript
  3. Confirm that TypeScript is installed. To do this, run the command line TypeScript compiler with the --version option.

    tsc --version

    If TypeScript is installed, the output contains the TypeScript version number.

Step 1.4: Install the AWS CDK

  1. Confirm whether you already have the AWS CDK installed. To do this, with the terminal session still open in the IDE, run the cdk command with the --version option.

    cdk --version

    If the AWS CDK is installed, the output contains the AWS CDK version and build numbers. Skip ahead to Step 2: Add Code.

  2. Install the AWS CDK by running the npm command along with the install action, the name of the AWS CDK package to install, and the -g option to install the package globally in the environment.

    npm install -g aws-cdk
  3. Confirm that the AWS CDK is installed and correctly referenced. To do this, run the cdk command with the --version option.

    cdk --version

    If successful, the AWS CDK version and build numbers are displayed.

Step 2: Add Code

In this step, you create a sample TypeScript project that contains all of the source code you need for the AWS CDK to programmatically deploy an AWS CloudFormation stack. This stack creates an Amazon SNS topic and an Amazon SQS queue in your AWS account and then subscribes the queue to the topic.

  1. With the terminal session still open in the IDE, create a directory to store the project's source code, for example a ~/environment/hello-cdk directory in your environment. Then switch to that directory.

    rm -rf ~/environment/hello-cdk # Remove this directory if it already exists. mkdir ~/environment/hello-cdk # Create the directory. cd ~/environment/hello-cdk # Switch to the directory.
  2. Set up the directory as a TypeScript language project for the AWS CDK. To do this, run the cdk command with the init action and the --language option along with the name of the programming language.

    cdk init --language typescript

    This creates the following files and subdirectories in the directory.

    • A hidden .git subdirectory and a hidden .gitignore file, which makes the project compatible with source control tools such as Git.

    • A bin subdirectory, which includes a hello-cdk.ts file. This file contains the code for your AWS CDK app and stack. This code is described in the next step in this procedure.

    • A node_modules subdirectory, which contains supporting code packages that the app and stack can use as needed.

    • A hidden .npmignore file, which lists the types of subdirectories and files that npm doesn't need when it builds the code.

    • A cdk.json file, which contains information to make running the cdk command easier.

    • A package-lock.json file, which contains information that npm can use to reduce possible build and run errors.

    • A package.json file, which contains information to make running the npm command easier and with possibly fewer build and run errors.

    • A README.md file, which lists useful commands you can run with npm and the AWS CDK.

    • A tsconfig.json file, which contains information to make running the tsc command easier and with possibly fewer build and run errors.

  3. In the Environment window, open the hello-cdk/bin/hello-cdk.ts file, and browse the following code in that file.

    #!/usr/bin/env node import sns = ('@aws-cdk/aws-sns'); import sqs = ('@aws-cdk/aws-sqs'); import cdk = ('@aws-cdk/cdk'); class HelloCdkStack extends cdk.Stack { constructor(parent: cdk.App, name: string, props?: cdk.StackProps) { super(parent, name, props); const queue = new sqs.Queue(this, 'HelloCdkQueue', { visibilityTimeoutSec: 300 }); const topic = new sns.Topic(this, 'HelloCdkTopic'); topic.subscribeQueue(queue); } } const app = new cdk.App(); new HelloCdkStack(app, 'HelloCdkStack'); app.run();
    • The App, Stack, StackProps, Topic, and Queue classes represent an executable program, an AWS CloudFormation stack and its properties, an Amazon SNS topic, and an Amazon SQS queue, respectively.

    • The HelloCdkStack class represents the AWS CloudFormation stack for this application. This stack contains the new Amazon SQS queue and Amazon SNS topic for this application.

    • The run method runs the application, which instructs AWS CloudFormation to deploy the stack.

  4. Use npm to run the TypeScript compiler to check for coding errors, and then enable the AWS CDK to execute the project's bin/hello-cdk.js file. To do this, from the project's root directory, run the npm command with the run action, specifying the build command value in the package.json file, as follows.

    npm run build

    The preceding command runs the TypeScript compiler, which adds a supporting bin/hello-cdk.d.ts file and also transpiles the bin/hello-cdk.ts file into a bin/hello-cdk.js file.

Step 3: Run the Code

In this step, you instruct the AWS CDK to create a AWS CloudFormation stack template based on the code in the bin/hello-cdk.js file. You then instruct the AWS CDK to deploy the stack, which creates the Amazon SNS topic and Amazon SQS queue and then subscribes the queue to the topic. You then confirm that the topic and queue were successfully deployed by sending a message from the topic to the queue.

  1. Have the AWS CDK create the AWS CloudFormation stack template. To do this, with the terminal session still open in the IDE, from the project's root directory, run the cdk command with the synth action and the name of the stack.

    cdk synth HelloCdkStack

    If successful, the output displays the AWS CloudFormation stack template's Resources section.

  2. Have the AWS CDK run the AWS CloudFormation stack template to deploy the stack. To do this, from the project's root directory, run the cdk command with the deploy action and the name of the stack.

    cdk deploy HelloCdkStack

    If successful, the output displays that the HelloCdkStack stack deployed without errors.

    Note

    If the output displays a message that the stack does not define an environment and that AWS credentials could not be obtained from standard locations or no region was configured, make sure that your AWS credentials are set correctly in the IDE, and then run the cdk deploy command again. For more information, see Call AWS Services from an Environment.

  3. To confirm that the Amazon SNS topic and Amazon SQS queue were successfully deployed, send a message to the topic, and then check the queue for the received message. To do this, you can use a tool such as the AWS Command Line Interface (AWS CLI) or the aws-shell. For more information about these tools, see the AWS CLI and aws-shell Sample.

    For example, to send a message to the topic, with the terminal session still open in the IDE, use the AWS CLI to run the Amazon SNS publish command, supplying the message's subject and body, the AWS Region for the topic, and the topic's Amazon Resource Name (ARN).

    aws sns publish --subject "Hello from the AWS CDK" --message "This is a message from the AWS CDK." --topic-arn arn:aws:sns:us-east-2:123456789012:HelloCdkStack-HelloCdkTopic1A234567-8BCD9EFGHIJ0K

    In the preceding command, replace arn:aws:sns:us-east-2:123456789012:HelloCdkStack-HelloCdkTopic1A234567-8BCD9EFGHIJ0K with the ARN that AWS CloudFormation assigns to the topic. To get the ID, you can run the Amazon SNS list-topics command.

    aws sns list-topics --output table --query 'Topics[*].TopicArn'

    If successful, the output of the publish command displays the MessageId value for the message that was published.

    To check the queue for the received message, run the Amazon SQS receive-message command, supplying the queue's URL.

    aws sqs receive-message --queue-url https://queue.amazonaws.com/123456789012/HelloCdkStack-HelloCdkQueue1A234567-8BCD9EFGHIJ0K

    In the preceding command, replace https://queue.amazonaws.com/123456789012/HelloCdkStack-HelloCdkQueue1A234567-8BCD9EFGHIJ0K with the ARN that AWS CloudFormation assigns to the queue. To get the URL, you can run the Amazon SQS list-queues command.

    aws sqs list-queues --output table --query 'QueueUrls[*]'

    If successful, the output of the receive-message command displays information about the message that was received.

Step 4: Clean Up

To prevent ongoing charges to your AWS account after you're done using this sample, you should delete the AWS CloudFormation stack. This deletes the the Amazon SNS topic and Amazon SQS queue. You should also delete the environment.

Step 4.1: Delete the Stack

With the terminal session still open in the IDE, from the project's root directory, run the cdk command with the destroy action and the stack's name.

cdk destroy HelloCdkStack

When prompted to delete the stack, type y, and then press Enter.

If successful, the output displays that the HelloCdkStack stack was deleted without errors.

Step 4.2: Delete the Environment

To delete the environment, see Deleting an Environment.