setup cdk project

Author: ferdingler

workshop/content/buildpipe/_index.en.md

@@ -8,8 +8,8 @@ pre = "<b>4. </b>"
 
 # Build the pipeline
 
-In this chapter you are going to automate the build, package and deploy commands by creating a continous delivery pipeline that, a high level, looks like the diagram below.  
+In this chapter you are going to learn how to automate the build, package and deploy commands by creating a continous delivery pipeline using AWS Code Pipeline. 
 
 ![SimplePipeline](/images/pipeline-art.png)
 
-The services used in this chapter are AWS CodeCommit, AWS CodeBuild, AWS CodePipeline, AWS CloudFormation and the AWS Serverless Application Repository.
+The services used in this chapter are CodeCommit, CodeBuild, CodePipeline, CloudFormation and the AWS CDK.

workshop/content/buildpipe/cdkinit/_index.en.md

@@ -0,0 +1,34 @@
++++
+title = "Setup a CDK project"
+date = 2019-11-01T15:26:09-07:00
+weight = 21
++++
+
+First of all, install the CDK CLI by running the following command from your terminal.
+```
+npm install -g aws-cdk
+```
+
+### Initialize project
+
+Now, let's create a folder within our _sam-app_ directory where the pipeline code will reside.
+```
+cd ~/environment/sam-app
+mkdir pipeline
+cd pipeline
+```
+
+Initialize a new CDK project within the _pipeline_ folder by running the following commands:
+
+```
+cdk init --language typescript
+npm install --save @aws-cdk/aws-codedeploy @aws-cdk/aws-codebuild
+npm install --save @aws-cdk/aws-codecommit @aws-cdk/aws-codepipeline-actions
+npm install --save @aws-cdk/aws-s3
+```
+
+After a few seconds, our new CDK project should look like this:
+
+![CdkInit](/images/chapter4/screenshot-cdk-init.png)
+
+The main file that you will be interacting with is the `lib/pipeline-stack.ts`. And the entry point of your CDK project is `bin/pipeline.ts`. For this workshop, don't worry about the rest of the files and folders, although if you are curious, feel free to poke around the project structure. 

workshop/content/buildpipe/launch/_index.en.md

@@ -4,62 +4,19 @@ date = 2019-11-01T15:26:09-07:00
 weight = 20
 +++
 
-The best way to automate the creation of CI/CD pipelines is by launching them programmatically. This is specially useful in a microservices environment, where you create a pipeline per microservice, which potentially means dozens of pipelines, if not more. Having an automated way to launch pipelines enables developers to create as many as they need without having to build them manually from the console every single time. 
+The best way to automate the creation of CI/CD pipelines is by provisioning them programmatically via Infrastructure as Code. This is specially useful in a microservices environment, where you have a pipeline per microservice, which potentially means dozens of pipelines, if not more. Having an automated way to create these pipelines enables developers to create as many as necessary without building them manually from the console every time.
 
-CloudFormation is just one of the many ways you can go about automating Pipeline creation. But there are a few other mechanisms we see customers use as pipeline vending machines. The following list describes some of the most common ones: 
+### Different ways to create pipelines
+We see customers using different mechanisms for creating pipelines programmatically.  The reality is that developers have many choices available, but the most common ones we see are the following:
 
 - [AWS CloudFormation](https://docs.aws.amazon.com/codepipeline/latest/userguide/tutorials.html)
 - [AWS CDK](https://docs.aws.amazon.com/cdk/latest/guide/codepipeline_example.html)
 - [Terraform](https://www.terraform.io/docs/providers/aws/r/codepipeline.html)
 - [AWS Serverless App Repository](https://serverlessrepo.aws.amazon.com/applications/arn:aws:serverlessrepo:us-east-1:646794253159:applications~aws-sam-codepipeline-cd)
 
-For this workshop, we are going to use CloudFormation as the vending mechanism. And we have already built a template that will help you get started. From your terminal, download the CloudFormation template:
+### Introducing the AWS CDK
+In this workshop, we are going to use the AWS Cloud Development Kit (CDK) as the pipeline vending mechanism. The AWS CDK is a software development framework for defining cloud infrastructure in code and provisioning it through AWS CloudFormation.
 
-```
-wget https://cicd.serverlessworkshops.io/assets/pipeline.yaml
-```
+That's right! You can describe your infrastructure by writing code in TypeScript, C#, Python or Java. Your code is then synthesized into CloudFormation and using the CDK CLI you can deploy it to an AWS account. 
 
-### Understanding the template (Optional)
-
-Let's take a moment to understand the key components of the CloudFormation template.
-
-#### The Artifacts Bucket
-
-This is the artifact store for your pipeline. CodePipeline will use this bucket to pass artifacts to the downstream jobs. This is also where SAM will upload the artifacts during the build process.
-![ArtifactsBucket](/images/screenshot-pipeline-yaml-bucket.png)
-
-#### The Source Stage
-
-The source stage is the first step of any pipeline and it points to your source code. It determines when to trigger the pipeline based on new changes (i.e. git push). This pipeline uses AWS CodeCommit as the source provider, but CodePipeline also supports S3, GitHub and Amazon ECR as source providers.
-
-![SourceStage](/images/screenshot-pipeline-yaml-source.png)
-
-#### The Build Stage
-
-The build phase uses AWS CodeBuild as the build provider. But CodePipeline supports other providers like Jenkins, TeamCity or CloudBees. CodeBuild is a great option because you only pay for the time when your build is running, which makes it very cost effective. 
-
-A CodeBuild project has information about the build environment. A build environment represents a combination of operating system (Linux or Windows), compute size (Small, Medium, Large) and a Docker image where the build runs. You can bring your own Docker image or [use the managed images](https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-available.html) provided by the service. In this case, we are using the managed image for Amazon Linux 2: aws/codebuild/amazonlinux2-x86_64-standard:1.0.
-
-![BuildStage](/images/screenshot-pipeline-yaml-build.png)
-
-#### The Deployment Stage
-
-This pipeline uses [CloudFormation ChangeSets](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets.html) to deploy the SAM application. This is why the deployment stage is composed of 2 steps, the _CreateChangeSet_ and the _ExecuteChangeSet_. The main thing to highlight here is the `TemplatePath`, notice how our deployment artifact is the `packaged.yaml` produced by the SAM build.
-
-![DeployStage](/images/screenshot-pipeline-yaml-deploy.png)
-
-#### The Pipeline Definition
-
-The pipeline definition is very straightforward. You specify the bucket for artifacts and a list of Stages, which in this case we have 3: `1. Source -> 2. Build -> 3. Deploy to Dev`. The configuration for each stage is ommited in the following image because it has already been shown in the screenshots above.
-
-![PipelineDefinition](/images/screenshot-pipeline-yaml-pipe.png)
-
-#### The IAM Roles
-
-In case you haven't noticed. This pipeline involves 3 different IAM Roles. It's important to be aware of them in case you need to troubleshoot a permissions error, depending on what stage of the pipeline you got it, you know what role to modify.
-
-- **CodeBuild Role:** Assumed by CodeBuild to write SAM artifacts to S3.
-- **Deployment Role:** Assumed by CloudFormation to create resources at the deploy stage.
-- **Pipeline Role:** Assumed by CodePipeline to invoke the different stages on your behalf.
-
-If you are curious, you can explore the IAM policies for each of these roles in the CloudFormation template.
+Continue on the next page to learn how to initialize a CDK project.