Minor fixes to CDK instructions

ferdingler · ferdingler · commit ba32aaee0916 · 2020-03-03T13:19:14.000-08:00
diff --git a/workshop/content/buildpipe/cdkinit/_index.en.md b/workshop/content/buildpipe/cdkinit/_index.en.md
@@ -18,10 +18,15 @@ mkdir pipeline
 cd pipeline
 ```
 
-Initialize a new CDK project within the _pipeline_ folder by running the following commands:
+Initialize a new CDK project within the _pipeline_ folder by running the following command:
 
 ```
 cdk init --language typescript
+```
+
+Now install the CDK modules that we will be using to build a pipeline: 
+
+```
 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
@@ -33,7 +38,30 @@ After a few seconds, our new CDK project should look like this:
 
 
 ### Project structure
-The main files that you will be interacting with are _lib/pipeline-stack.ts_ and _bin/pipeline.ts_. Don't worry about the rest of the files and folders for now. Open the `bin/pipeline.ts` file, which is your entry point to the CDK project, and change the name of the stack to `sam-app-cicd`: 
+
+At this point, your project should have the structure below (only the most relevant files and folders are shown). Within the CDK project, the main file you will be interacting with is the _pipeline-stack.ts_. Don't worry about the rest of the files for now. 
+
+```
+sam-app                         # SAM application root
+├── hello-world                 # Lambda code
+├── samconfig.toml              # Config file for manual deployments
+├── template.yaml               # SAM template
+└── pipeline                    # CDK project root
+    └── lib
+        └── pipeline-stack.ts   # Pipeline definition
+    └── bin
+        └── pipeline.ts         # Entry point for CDK project
+    ├── cdk.json
+    ├── tsconfig.json
+    ├── package.json
+    └── jest.config.js
+```
+
+### Modify stack name
+
+Open the `bin/pipeline.ts` file, which is your entry point to the CDK project, and change the name of the stack to **sam-app-cicd**. 
 
 ![CdkEntryPoint](/images/chapter4/screenshot-bin-pipeline-ts.png)
 
+**Save the file**.
+
diff --git a/workshop/content/buildpipe/done/_index.en.md b/workshop/content/buildpipe/done/_index.en.md
@@ -4,7 +4,7 @@ date = 2019-11-05T14:20:52-08:00
 weight = 35
 +++
 
-Once your pipeline has finished every stage successfully, it should look like the following screenshot:
+Let your pipline run every stage. After it finishes it will look all green like the following screenshot:
 
 ![VerifyPipelineRunning](/images/chapter4/screenshot-pipeline-verify-3.png)
 
diff --git a/workshop/content/buildpipe/howto/_index.en.md b/workshop/content/buildpipe/howto/_index.en.md
@@ -7,16 +7,18 @@ weight = 20
 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.
 
 ### 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:
+We see customers using different mechanisms for creating pipelines programmatically. Nowadays developers have many choices to pick from, 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)
 
 ### 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.
+In this workshop, we are going to use the AWS Cloud Development Kit (also known as 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.
 
 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. 
 
-Continue on the next page to learn how to initialize a CDK project.
+### How does SAM and CDK play together?
+
+Serverless developers use the SAM framework to define their applications, SAM CLI to build them and deploy them and AWS CDK to provision any infrastructure related resources, like their CI/CD Pipeline. The nice thing about these tools is that they all share a common ground: CloudFormation. 
diff --git a/workshop/content/buildpipe/pipeascode/_index.en.md b/workshop/content/buildpipe/pipeascode/_index.en.md
@@ -4,7 +4,7 @@ date = 2019-11-01T15:26:09-07:00
 weight = 22
 +++
 
-Open the file `lib/pipeline-stack.ts` in your Cloud9 workspace. It is empty at the moment, but you will be adding code to describe and build your CI/CD pipeline in the following pages.
+Open the file `lib/pipeline-stack.ts` in your Cloud9 workspace. It is empty at the moment, but here is where you will be adding code to build your CI/CD pipeline.
 
 ![CdkEmptyLib](/images/chapter4/screenshot-cdk-empty.png)
 
diff --git a/workshop/content/buildpipe/pipeascode/bucket/_index.en.md b/workshop/content/buildpipe/pipeascode/bucket/_index.en.md
@@ -8,6 +8,8 @@ Every Code Pipeline needs an artifacts bucket, also known as Artifact Store. Cod
 
 Let's get started and write the code for creating this bucket:
 
+**Make sure you are editing the file with _.ts_ extension**
+
 ```js
 // lib/pipeline-stack.ts
 
@@ -31,6 +33,10 @@ npm run build
 cdk deploy
 ```
 
+{{% notice info %}}
+If you get a build error, check that all the @aws-cdk dependencies in the package.json file have the same version number, if not, fix it, delete the node_modules folder and run npm install. More info: https://github.com/aws/aws-cdk/issues/542#issuecomment-449694450.
+{{% /notice %}}
+
 The output will show that the S3 bucket got created:
 
 ![CdkBucket](/images/chapter4/screenshot-cdk-s3-bucket.png)
diff --git a/workshop/content/buildpipe/pipeascode/build/_index.en.md b/workshop/content/buildpipe/pipeascode/build/_index.en.md
@@ -4,10 +4,14 @@ date = 2019-11-01T15:26:09-07:00
 weight = 20
 +++
 
-The build stage is where your Serverless application gets built and packaged. We are going to use AWS CodeBuild as the Build provider for our pipeline. It is worth mentioning that CodePipeline also supports other providers like Jenkins, TeamCity or CloudBees. 
+The **Build Stage** is where your Serverless application gets built and packaged by SAM. We are going to use AWS CodeBuild as the Build provider for our pipeline. It is worth mentioning that CodePipeline also supports other providers like Jenkins, TeamCity or CloudBees. 
+
+### Why AWS Code Build?
 
 AWS CodeBuild is a great option because you only pay for the time where your build is running, which makes it very cost effective compared to running a dedicated build server 24 hours a day when you really only build during office hours. It is also container-based which means that you can bring your own Docker container image where your build runs, or [use a managed image](https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-available.html) provided by CodeBuild.  
 
+### Add the build stage
+
 Let's go ahead and add a Build stage to our pipeline:
 
 ```js
@@ -99,7 +103,7 @@ Navigate to the [AWS CodePipeline Console](https://console.aws.amazon.com/codesu
 
 ![VerifyPipeline](/images/chapter4/screenshot-pipeline-verify-1.png)
 
-Oh no! the Build step failed. **Don't worry, this is expected** because we haven't specified what commands to run on the build yet so AWS CodeBuild doesn't know how to build our Serverless application.
+The Build step should have failed. **Don't worry! this is expected** because we haven't specified what commands to run during the build yet, so AWS CodeBuild doesn't know how to build our Serverless application.
 
 ![VerifyPipeline](/images/chapter4/screenshot-pipeline-verify-2.png)
 
diff --git a/workshop/content/buildpipe/pipeascode/buildspec/_index.en.md b/workshop/content/buildpipe/pipeascode/buildspec/_index.en.md
@@ -4,7 +4,7 @@ date = 2019-10-04T12:54:48-07:00
 weight = 30
 +++
 
-A buildspec file is a series of commands in YAML format that CodeBuild executes to build your application. This file is placed in the root folder of a SAM application and CodeBuild will automatically find it and run it during build time.
+A **Buildspec File** is a series of commands in YAML format that CodeBuild executes to build your application. This file is placed in the root folder of a SAM application and CodeBuild will automatically find it and run it during build time.
 
 In your Cloud9 editor, create a new file named `buildspec.yml` in the root (top level) of the _sam-app_ directory by right clicking on the `sam-app` folder and selecting New file.
 
@@ -63,9 +63,11 @@ artifacts:
 Take a moment to understand the structure of the file and feel free to read the Buildsec Reference here: https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html.
 
 ### Push code changes
+
 Commit your changes and push them to the repository.
 
 ```
+cd ~/environment/sam-app
 git add .
 git commit -m "Added buildspec.yml"
 git push
diff --git a/workshop/content/buildpipe/pipeascode/deploy/_index.en.md b/workshop/content/buildpipe/pipeascode/deploy/_index.en.md
@@ -4,7 +4,7 @@ date = 2019-10-04T12:54:48-07:00
 weight = 40
 +++
 
-The deploy stage is where your SAM application and all its resources are created an in an AWS account. The most common way to do this is by using CloudFormation ChangeSets to deploy. This means that this stage will have 2 actions: the _CreateChangeSet_ and the _ExecuteChangeSet_.
+The **Deploy Stage** is where your SAM application and all its resources are created an in an AWS account. The most common way to do this is by using CloudFormation ChangeSets to deploy. This means that this stage will have 2 actions: the _CreateChangeSet_ and the _ExecuteChangeSet_.
 
 Add the Deploy stage to your pipeline: 
 
@@ -108,11 +108,12 @@ export class PipelineStack extends cdk.Stack {
 On your terminal, run the following commands from within the _pipeline_ directory:
 
 ```
+cd ~/environment/sam-app/pipeline
 npm run build
 cdk deploy
 ```
 
-The CDK CLI might ask you to confirm the changes before deploying, this is because we are giving Admin permissions to the IAM role that deploys our application. This is generally not a bad practice since this role can only be assumed by CloudFormation and not by a human, however, if your organization has a stricter security posture you may want to consider providing a fine grain policy for the deployment role. 
+The CLI might ask you to confirm the changes before deploying, this is because we are giving Admin permissions to the IAM role that deploys our application. This is generally **not** a bad practice since this role can only be assumed by CloudFormation and not by a human, however, if your organization has a stricter security posture you may want to consider creating [a custom IAM deployment role](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-iam.Role.html) with a fine grain policy. 
 
 ### Trigger a release
 
diff --git a/workshop/content/buildpipe/pipeascode/source/_index.en.md b/workshop/content/buildpipe/pipeascode/source/_index.en.md
@@ -4,7 +4,7 @@ date = 2019-11-01T15:26:09-07:00
 weight = 15
 +++
 
-The source stage is the first step of any CI/CD pipeline and it represents your source code. This stage is in charge of triggering the pipeline based on new code changes (i.e. git push or pull requests). In this workshop, we will be using AWS CodeCommit as the source provider, but CodePipeline also supports S3, GitHub and Amazon ECR as source providers.
+The **Source Stage** is the first step of any CI/CD pipeline and it represents your source code. This stage is in charge of triggering the pipeline based on new code changes (i.e. git push or pull requests). In this workshop, we will be using AWS CodeCommit as the source provider, but CodePipeline also supports S3, GitHub and Amazon ECR as source providers.
 
 Let's go ahead and add a Source provider to our pipeline:
 
diff --git a/workshop/content/manualdeploy/_index.en.md b/workshop/content/manualdeploy/_index.en.md
@@ -11,4 +11,4 @@ Before we start building a fully automated continous delivery pipeline, in this
 
 ![ManualDeploy](/images/manual-deploy-art.png)
 
-Even though this workshop is about automating deployments, this chapter is very important to learn the foundation of how to package and deploy a Serverless application. You need to learn the basic commands that you will be automating with a pipeline in the next chapter.
+Even though this workshop is about automating deployments, this chapter is very important to learn the foundation of how to package and deploy a Serverless application. Learning how to perform manual deployments is also useful for developers who want to create their own personal stack and deploy it often to test changes before commiting them to the source control repository.
diff --git a/workshop/content/manualdeploy/deploy/_index.en.md b/workshop/content/manualdeploy/deploy/_index.en.md
@@ -4,9 +4,9 @@ date = 2019-10-03T13:33:54-07:00
 weight = 20
 +++
 
-The `sam deploy` command deploys your application by launching a CloudFormation stack. This command now comes with a guided interactive mode, which you can enable by specifying the _--guided_ parameter. It walks you through the parameters required for deployment, provides default options, and saves these options in a configuration file in your project folder.
+The `sam deploy` command deploys your application by launching a CloudFormation stack. This command has a guided interactive mode, which you enable by specifying the _--guided_ parameter. It is recommended to deploy with guided mode for the first time as it will capture the configuration for future deployments.
 
-Run the following command in the same directory level where the _packaged.yaml_ is located:
+Run the following command in the same directory level where the _template.yaml_ is located:
 
 ```
 sam deploy --guided
diff --git a/workshop/content/setup/bootstrap/_index.en.md b/workshop/content/setup/bootstrap/_index.en.md
@@ -39,4 +39,4 @@ Run the following command:
 sam --version
 ```
 
-You should see *SAM CLI, version 0.31.1* or greater.
+You should see *SAM CLI, version 0.43.0* or greater.
diff --git a/workshop/static/assets/bootstrap.sh b/workshop/static/assets/bootstrap.sh
@@ -0,0 +1,83 @@
+#!/bin/bash
+
+# Cloud9 Bootstrap Script
+#
+# 1. Installs homebrew
+# 2. Upgrades to latest AWS CLI
+# 3. Upgrades AWS SAM CLI
+#
+# Usually takes about 8 minutes to complete
+
+set -euxo pipefail
+
+ACCOUNT_ID=$(aws sts get-caller-identity --query 'Account' --output text)
+CURRENT_REGION=$(curl -s http://169.254.169.254/latest/meta-data/placement/availability-zone | sed 's/\(.*\)[a-z]/\1/')
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+export INFOPATH="/home/linuxbrew/.linuxbrew/share/info"
+
+function _logger() {
+    echo -e "$(date) ${YELLOW}[*] $@ ${NC}"
+}
+
+function upgrade_sam_cli() {
+    _logger "[+] Backing up current SAM CLI"
+    cp $(which sam) ~/.sam_old_backup
+
+    _logger "[+] Installing latest SAM CLI"
+    # pipx install aws-sam-cli
+    # cfn-lint currently clashing with SAM CLI deps
+    ## installing SAM CLI via brew instead
+    brew tap aws/tap
+    brew install aws-sam-cli
+
+    _logger "[+] Updating Cloud9 SAM binary"
+    # Allows for local invoke within IDE (except debug run)
+    ln -sf $(which sam) ~/.c9/bin/sam
+}
+
+function upgrade_existing_packages() {
+    _logger "[+] Upgrading system packages"
+    sudo yum update -y
+
+    _logger "[+] Upgrading Python pip and setuptools"
+    python3 -m pip install --upgrade pip setuptools --user
+
+    _logger "[+] Installing latest AWS CLI"
+    # _logger "[+] Installing pipx, and latest AWS CLI"
+    # python3 -m pip install --user pipx
+    # pipx install awscli
+    python3 -m pip install --upgrade --user awscli
+}
+
+function install_utility_tools() {
+    _logger "[+] Installing jq"
+    sudo yum install -y jq
+}
+
+function install_linuxbrew() {
+    _logger "[+] Creating touch symlink"
+    sudo ln -sf /bin/touch /usr/bin/touch
+    _logger "[+] Installing homebrew..."
+    echo | sh -c "$(curl -fsSL https://raw.githubusercontent.com/Linuxbrew/install/master/install.sh)"
+    _logger "[+] Adding homebrew in PATH"
+    test -d ~/.linuxbrew && eval $(~/.linuxbrew/bin/brew shellenv)
+    test -d /home/linuxbrew/.linuxbrew && eval $(/home/linuxbrew/.linuxbrew/bin/brew shellenv)
+    test -r ~/.bash_profile && echo "eval \$($(brew --prefix)/bin/brew shellenv)" >>~/.bash_profile
+    echo "eval \$($(brew --prefix)/bin/brew shellenv)" >>~/.profile
+}
+
+function main() {
+    upgrade_existing_packages
+    install_linuxbrew
+    install_utility_tools
+    upgrade_sam_cli
+
+    echo -e "${RED} [!!!!!!!!!] Open up a new terminal to reflect changes ${NC}"
+    _logger "[+] Restarting Shell to reflect changes"
+    exec ${SHELL}
+}
+
+main

Original file line number	Diff line number	Diff line change
`@@ -11,4 +11,4 @@ Before we start building a fully automated continous delivery pipeline, in this`
`11`	`11`
`12`	`12`	`![ManualDeploy](/images/manual-deploy-art.png)`
`13`	`13`
`14`		`-Even though this workshop is about automating deployments, this chapter is very important to learn the foundation of how to package and deploy a Serverless application. You need to learn the basic commands that you will be automating with a pipeline in the next chapter.`
	`14`	`+Even though this workshop is about automating deployments, this chapter is very important to learn the foundation of how to package and deploy a Serverless application. Learning how to perform manual deployments is also useful for developers who want to create their own personal stack and deploy it often to test changes before commiting them to the source control repository.`