Merge pull request #14 from aws-samples/dev

Release v2.0.1

Author: ferdingler

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

@@ -4,8 +4,11 @@ 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.
+## Install the latest CDK
+
+If you are using Cloud9, the CDK is already pre-installed but it will likely be a few versions old. Run the following commands from the Cloud9 terminal to remove your current version and install the latest one:
 ```
+npm uninstall -g aws-cdk
 npm install -g aws-cdk
 ```
 

workshop/content/canaries/rollbacks/faketraffic/_index.en.md

@@ -10,7 +10,7 @@ In your terminal, run the following command to invoke the Lambda function:
 
 ```
 aws lambda invoke --function-name \
-$(aws lambda list-functions | jq -r .Functions[0].FunctionName):live \
+$(aws lambda list-functions | jq -r -c '.Functions[] | select( .FunctionName | contains("sam-app-HelloWorldFunction")).FunctionName'):live \
 --payload '{}' \
 response.json
 ```
@@ -34,7 +34,7 @@ counter=1
 while [ $counter -le 15 ]
 do
     aws lambda invoke --function-name \
-    $(aws lambda list-functions | jq -r .Functions[0].FunctionName):live \
+    $(aws lambda list-functions | jq -r -c '.Functions[] | select( .FunctionName | contains("sam-app-HelloWorldFunction")).FunctionName'):live \
     --payload '{}' \
     response.json
     sleep 1

workshop/content/crossaccount/_index.en.md

@@ -2,13 +2,13 @@
 title = "Cross Account Deployments"
 date = 2019-10-02T16:10:44-07:00
 weight = 40
-chapter = true
+chapter = false
 draft = true
 hidden = true
 pre = "<b>6. </b>"
 +++
 # Cross Account Deployments
 
-Cross-account deployments are useful for customers who separate their environments (Dev, Test, Prod) into different AWS accounts. In this chapter you will learn how to deploy across multiple accounts using AWS Code Pipeline.
+Cross-account deployments are useful for customers who separate their environments (Dev, Test, Prod) into different AWS accounts. In this chapter you will learn how to deploy a Serverless application across multiple accounts using Code Pipeline.
 
-![DevWorkflow](/images/cross-account-chapter.png)
+![DevWorkflow](/images/chapter6/cross-account-chapter.png)

workshop/content/crossaccount/artifactstore/_index.en.md

@@ -0,0 +1,49 @@
++++
+title = "CDK prod environment"
+date = 2019-11-11T14:46:02-08:00
+weight = 35
+draft = true
+hidden = true
++++
+
+Before we define any resources in the stack, we need to configure the CDK project to deploy this stack in the Production account. For this, the CDK has the concept of [Environments](https://docs.aws.amazon.com/cdk/latest/guide/environments.html), which allows you to deploy Stacks in different AWS accounts from within the same CDK project. 
+
+Open the file `bin/pipeline.ts` and replace its content with the following snippet:
+
+{{< highlight js "hl_lines=11 17" >}}
+#!/usr/bin/env node
+import 'source-map-support/register';
+import * as cdk from '@aws-cdk/core';
+import { PipelineStack } from '../lib/pipeline-stack';
+import { ProdIAMStack } from '../lib/prod-iam-stack';
+
+const app = new cdk.App();
+
+new PipelineStack(app, 'sam-app-cicd', {
+    env: {
+        account: '0123456789', // dev account
+    }
+});
+
+new ProdIAMStack(app, 'sam-app-iam-cross-account', {
+    env: {
+        account: '9876543210', // prod account
+    }
+});
+{{< / highlight >}}
+
+**NOTE**: Replace the account IDs corresponding to your dev and production AWS accounts.
+
+{{% notice tip %}}
+The command `aws sts get-caller-identity` is an easy way to get your AWS Account ID. You can also check here for other forms to find it: https://docs.aws.amazon.com/IAM/latest/UserGuide/console_account-alias.html.
+{{% /notice%}}
+
+### Test deployment
+
+```
+cd ~/environment/sam-app/pipeline
+npm run build
+cdk deploy sam-app-iam-cross-account --profile prod
+```
+
+

workshop/content/crossaccount/cdkprodenv/_index.en.md

@@ -0,0 +1,85 @@
++++
+title = "Cross account roles"
+date = 2019-11-11T14:46:02-08:00
+weight = 40
+draft = true
+hidden = true
++++
+
+Now that we have verified that we can deploy an empty stack to production, lets create the actual cross account roles in the `lib/prod-iam-stack.ts` file we created earlier. Add the following content to the file:
+
+{{< highlight js "hl_lines=26" >}}
+import * as cdk from '@aws-cdk/core';
+import iam = require('@aws-cdk/aws-iam');
+
+export class ProdIAMStack extends cdk.Stack {
+    constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) {
+      super(scope, id, props);
+
+      /**
+       * IAM Deployer Role. Will be used to deploy 
+       * the serverless app. Needs admin permissions.
+       */
+      const deployerRole = new iam.Role(this, 'DeployerRole', {
+        assumedBy: new iam.ServicePrincipal('cloudformation.amazonaws.com')
+      });
+
+      deployerRole.addManagedPolicy(
+          iam.ManagedPolicy.fromAwsManagedPolicyName("AdministratorAccess")
+      );
+
+      /**
+       * IAM Cross Account Access Role. Will be assumed by
+       * the CodePipeline in the dev account, needs permissions
+       * to pass the Deployer role defined above.
+       */
+      const crossAccountRole = new iam.Role(this, 'CrossAccountRole', {
+          assumedBy: new iam.AccountPrincipal("REPLACE ME"), // replace with dev account id
+      });
+
+      // Needs CloudFormation permissions
+      crossAccountRole.addManagedPolicy(
+          iam.ManagedPolicy.fromAwsManagedPolicyName("AWSCloudFormationFullAccess")
+      );
+
+      // Needs permissions to pass the deployer role defined above
+      crossAccountRole.addToPolicy(new iam.PolicyStatement({
+          actions: ['iam:PassRole'],
+          resources: [deployerRole.roleArn]
+      }));
+
+      // Needs S3 permissions to access artifacts in the DEV account
+      crossAccountRole.addToPolicy(new iam.PolicyStatement({
+          actions: ['s3:GetObject'],
+          resources: ['*']
+      }));
+
+      // Needs KMS permissions to decrypt objects in the DEV account
+      crossAccountRole.addToPolicy(new iam.PolicyStatement({
+          actions: ['kms:Decrypt'],
+          resources: ['*']
+      }));
+
+      /**
+       * Outputs
+       */
+      new cdk.CfnOutput(this, 'ProdCrossAccountRoleArn', {
+          value: crossAccountRole.roleArn,
+      });
+
+      new cdk.CfnOutput(this, 'DeployerRoleArn', {
+        value: deployerRole.roleArn,
+      });
+
+    }
+}
+{{< / highlight >}}
+
+**NOTE:** Replace the highlighted line with the corresponding DEV account id.
+
+### Deploy stack
+
+```
+npm run build
+cdk deploy sam-app-iam-cross-account --profile prod
+```

workshop/content/crossaccount/crossaroles/_index.en.md

@@ -1,5 +1,5 @@
 +++
-title = "How does it work"
+title = "How it works"
 date = 2019-11-11T14:46:02-08:00
 weight = 20
 draft = true
@@ -8,15 +8,15 @@ hidden = true
 
 Before jumping to the implementation, we need to understand the different pieces that allow Code Pipeline to deploy across a different account. The following diagram shows a zoomed-in view of the services and roles involved in this process. 
 
-![CrossAccountDeploy](/images/cross-account-deploy.png)
+![CrossAccountDeploy](/images/chapter6/cross-account-deploy.png)
 
 #### Explanation
 
-The diagram above illustrates what happens when CodePipeline begins a deployment to the Production account. The first step is to assume the **IAM Pipeline Role** that exists in the Production account; This is possible because the role has a Trust Policy that allows the Development account to assume it. The second step is CodePipeline uses that role to trigger a deployment in CloudFormation by passing the **IAM Deployer Role**. This action is called [PassRole](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_passrole.html) and is needed for CloudFormation to create resources on your behalf. Finally, as you learned in previous chapters, CloudFormation gets the deployment artifacts from S3 and decrypts them by using the KMS Customer Managed Key. 
+The diagram above illustrates what happens when CodePipeline begins a deployment to the Production account. The first step is to assume the **IAM Cross Account Role** that exists in the Production account; This is possible because the role has a Trust Policy that allows the Dev account to assume it. The second step is CodePipeline uses that role to trigger a deployment in CloudFormation by passing the **IAM Deployer Role**. This action is called [PassRole](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_passrole.html) and is needed for CloudFormation to create resources on your behalf. Finally, as you learned in previous chapters, CloudFormation gets the deployment artifacts from S3 and decrypts them by using the KMS Customer Managed Key. 
 
 #### Why encrypt the artifacts?
 
-AWS CodePipeline *always* stores artifacts on S3 with encryption enabled and there is no way to disable it. The default behavior is to use the AWS Managed Key to encrypt them, but this approach doesn't work for granting access to S3 buckets across accounts. Therefore you [3] must create a KMS Customer Master Key and then give the IAM role in the Production account permissions to use it to decrypt the artifacts. 
+AWS CodePipeline *always* stores artifacts on S3 with encryption-at-rest enabled and there is no way to disable it. The default behavior is to use the AWS Managed Key to encrypt them, but this approach doesn't work for granting access to S3 buckets across accounts. Therefore you [3] must create a KMS Customer Master Key and then give the IAM role in the Production account permissions to use it to decrypt the artifacts. 
 
 #### Additional reading
 

workshop/content/crossaccount/howitworks/_index.en.md

@@ -8,10 +8,10 @@ hidden = true
 
 ### Environment separation
 
-Separating environments (Dev, Test, Prod) into different AWS accounts is a very common practice among AWS customers. And the main motivation being the ability to give developers full administrative access to the Dev environment, so that they can innovate and iterate quickly, but give them _limited_ access to higher environments, like Production. There are other motivations as well, like managing [AWS Service Quotas](https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html) separately and having billing details broken down per environment. 
+Separating environments into different AWS accounts its a common practice among AWS customers. The most basic form of separation is to have 2 AWS accounts, one for non-production environments and one dedicated to Production. This gives developers the ability to have full admin permissions in the Dev environment, to iterate and experiment quickly, and have _limited_ permissions in the Production account.
 
-The following diagram illustrates a simple account setup that many customers start with. And we will also be using it throughout this chapter. But the concepts that you will learn here can be applied to any form of multi-account setup. 
+The following diagram illustrates a simple setup of 2 accounts, one for Dev and one for Prod. This is the setup we will be using as reference throughout this chapter, but the concepts learned can be applied to any form of multi-account setup. 
 
-![EnvironmentSeparation](/images/environment-separation.png)
+![EnvironmentSeparation](/images/chapter6/environment-separation.png)
 
-As you can tell from the diagram, the Dev account hosts the Code Pipeline, Artifacts Bucket and the Code Repository. The CodePipeline then deploys across the Production account using an [assumed role](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html).
+As you can see from the diagram, the Dev account hosts the Code Pipeline, S3 bucket for artifacts and the code repository. The pipeline then deploys across the Production account using IAM [assumed roles](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html).

workshop/content/crossaccount/intro/_index.en.md

@@ -0,0 +1,11 @@
++++
+title = "Create Prod credentials"
+date = 2019-11-11T14:46:02-08:00
+weight = 22
+draft = true
+hidden = true
++++
+
+In this chapter you will be deploying to both, the DEV account and the PROD account from your Cloud9 environment, for that to work you need to have valid IAM credentials and profiles configured in your ~/.aws/credentials file.
+
+**TODO: ADD STEPS TO CONFIGURE CREDENTIALS**

workshop/content/crossaccount/prodcredentials/_index.en.md

@@ -0,0 +1,36 @@
++++
+title = "Prod account setup"
+date = 2019-11-11T14:46:02-08:00
+weight = 30
+draft = true
+hidden = true
++++
+
+Let's get started creating the necessary IAM roles in the Production account to grant cross account access. We will do this as a separate stack within the same CDK project created in Chapter 4.
+
+Run the following command to create a new file named _prod-iam-stack.ts_ inside the _lib_ drectory. 
+
+```
+cd ~/environment/sam-app/pipeline
+touch lib/prod-iam-stack.ts
+```
+
+Paste to following content inside the file: 
+
+```js
+import * as cdk from '@aws-cdk/core';
+import iam = require('@aws-cdk/aws-iam');
+
+export class ProdIAMStack extends cdk.Stack {
+    constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) {
+      super(scope, id, props);
+
+      // Resource definition goes here
+    }
+}
+```
+
+It should look like this: 
+
+![NewIamProdStack](/images/chapter6/new-file-prod-stack.png)
+