• Step 5: Clean up (p. 159)
Prerequisites
To complete this tutorial, you must first:
• Complete the steps in Getting started with CodeDeploy (p. 31).
• Install the AWS Serverless Application Model CLI. For information, see Install the AWS SAM CLI.
• Create an S3 bucket. AWS SAM uploads the artifacts that are referenced in your AWS SAM template into this bucket.
Step 1: Set up your infrastructure
This topic shows you how to use AWS SAM to create files for your AWS SAM template and your Lambda functions. Then, you use the AWS SAM package and deploy commands to generate the components in your infrastructure. When your infrastructure is ready, you have a CodeDeploy application and deployment group, the Lambda function to update and deploy, and two Lambda functions that contain
Step 1: Set up your infrastructure
validation tests that run when you deploy the Lambda function. When complete, you can use AWS CloudFormation to view your components and the Lambda console or the AWS CLI to test your Lambda function.
Topics
• Create your files (p. 144)
• Package the AWS SAM application (p. 151)
• Deploy the AWS SAM application (p. 152)
• (Optional) inspect and test your infrastructure (p. 152)
Create your files
To create your infrastructure, you must create the following files:
• template.yml
• myDateTimeFunction.js
• beforeAllowTraffic.js
• afterAllowTraffic.js
Topics
• Create your AWS SAM template (p. 144)
• Create a file for your Lambda function (p. 147)
• Create a file for your BeforeAllowTraffic Lambda function (p. 149)
• Create a file for your AfterAllowTraffic Lambda function (p. 150)
Create your AWS SAM template
Create an AWS SAM template file that specifies the components in your infrastructure.
To create your AWS SAM template
1. Create a directory named SAM-Tutorial.
2. In your SAM-Tutorial directory, create a file named template.yml.
3. Copy the following YAML code into template.yml. This is your AWS SAM template.
AWSTemplateFormatVersion : '2010-09-09' Transform: AWS::Serverless-2016-10-31
Description: A sample SAM template for deploying Lambda functions.
Resources:
✔ Details about the myDateTimeFunction Lambda function myDateTimeFunction:
Type: AWS::Serverless::Function Properties:
Handler: myDateTimeFunction.handler Runtime: nodejs10.x
✔ Instructs your myDateTimeFunction is published to an alias named "live".
AutoPublishAlias: live
✔ Grants this function permission to call lambda:InvokeFunction
Step 1: Set up your infrastructure
Action:
- "lambda:InvokeFunction"
Resource: '*' DeploymentPreference:
✔ Specifies the deployment configuration Type: Linear10PercentEvery1Minute
✔ Specifies Lambda functions for deployment lifecycle hooks Hooks:
PreTraffic: !Ref beforeAllowTraffic PostTraffic: !Ref afterAllowTraffic
✔ Specifies the BeforeAllowTraffic lifecycle hook Lambda function beforeAllowTraffic:
Type: AWS::Serverless::Function Properties:
Handler: beforeAllowTraffic.handler Policies:
- Version: "2012-10-17"
✔ Grants this function permission to call
codedeploy:PutLifecycleEventHookExecutionStatus Statement:
- Effect: "Allow"
Action:
- "codedeploy:PutLifecycleEventHookExecutionStatus"
Resource:
!Sub 'arn:aws:codedeploy:${AWS::Region}:
${AWS::AccountId}:deploymentgroup:${ServerlessDeploymentApplication}/*' - Version: "2012-10-17"
✔ Grants this function permission to call lambda:InvokeFunction Statement: FunctionName: 'CodeDeployHook_beforeAllowTraffic' DeploymentPreference:
✔ Specifies the AfterAllowTraffic lifecycle hook Lambda function afterAllowTraffic:
Type: AWS::Serverless::Function Properties:
Handler: afterAllowTraffic.handler Policies:
- Version: "2012-10-17"
Statement:
✔ Grants this function permission to call
codedeploy:PutLifecycleEventHookExecutionStatus - Effect: "Allow"
Action:
- "codedeploy:PutLifecycleEventHookExecutionStatus"
Resource:
!Sub 'arn:aws:codedeploy:${AWS::Region}:
${AWS::AccountId}:deploymentgroup:${ServerlessDeploymentApplication}/*' - Version: "2012-10-17"
Statement:
✔ Grants this function permission to call lambda:InvokeFunction - Effect: "Allow"
Action:
- "lambda:InvokeFunction"
Step 1: Set up your infrastructure
Resource: !Ref myDateTimeFunction.Version Runtime: nodejs10.x
✔ Specifies the name of the Lambda hook function FunctionName: 'CodeDeployHook_afterAllowTraffic' DeploymentPreference:
Enabled: false Timeout: 5 Environment:
Variables:
NewVersion: !Ref myDateTimeFunction.Version
This template specifies the following. For more information, see AWS SAM template concepts.
A Lambda function called myDateTimeFunction
When this Lambda function is published, the AutoPublishAlias line in the template links it to an alias named live. Later in this tutorial, an update to this function triggers a deployment by AWS CodeDeploy that incrementally shifts production traffic from the original version to the updated version.
Two Lambda deployment validation functions
The following Lambda functions are executed during CodeDeploy lifecycle hooks. The functions contain code that validate the deployment of the updated myDateTimeFunction. The result of the validation tests are passed to CodeDeploy using its PutLifecycleEventHookExecutionStatus API method. If a validation test fails, the deployment fails and is rolled back.
• CodeDeployHook_beforeAllowTraffic runs during the BeforeAllowTraffic hook.
• CodeDeployHook_afterAllowTraffic runs during the AfterAllowTraffic hook.
The name of both functions start with CodeDeployHook_. The CodeDeployRoleForLambda role allows calls to the Lambda invoke method only in Lambda functions with names that start with this prefix. For more information, see AppSpec 'hooks' section for an AWS Lambda deployment (p. 394) and PutLifecycleEventHookExecutionStatus in the CodeDeploy API Reference.
Automatic detection of an updated Lambda function
The AutoPublishAlias term tells the framework to detect when the myDateTimeFunction function changes, and then deploy it using the live alias.
A deployment configuration
The deployment configuration determines the rate at which your CodeDeploy application shifts traffic from the original version of the Lambda function to the new version. This template specifies the predefined deployment configuration Linear10PercentEvery1Minute.
NoteYou cannot specify a custom deployment configuration in an AWS SAM template. For more information, see Create a Deployment Configuration (p. 249).
Deployment lifecycle hook functions
The Hooks section specifies the functions to run during lifecycle event hooks. PreTraffic specifies the function that runs during the BeforeAllowTraffic hook. PostTraffic specifies the function that runs during the AfterAllowTraffic hook.
Permissions for Lambda to invoke another Lambda function
The specified lambda:InvokeFunction permission grants the role used by the AWS
Step 1: Set up your infrastructure
Create a file for your Lambda function
Create the file for the function you update and deploy later in this tutorial.
NoteA Lambda function can use any runtime supported by AWS Lambda. For more information, see AWS Lambda runtimes.
To create your Lambda function
1. Create a text file and save it as myDateTimeFunction.js in the SAM-Tutorial directory.
2. Copy the following Node.js code into myDateTimeFunction.js.
'use strict';
exports.handler = function(event, context, callback) {
Step 1: Set up your infrastructure
headers: { "Content-type": "application/json" }, body: JSON.stringify( result )
The Lambda function returns the day, month, and year for yesterday, today, or tomorrow. Later in this tutorial, you uncomment code that updates the function to return information about the day or time you specify (for example, the day, month, and year, or the current hour, minute, and second). The framework created by AWS SAM detects and deploys the updated version of the function.
NoteThis Lambda function is also used in an AWS Cloud9 tutorial. AWS Cloud9 is a cloud-based integrated development environment. For information about how to create, execute, update, and debug this function in AWS Cloud9, see AWS Lambda tutorial for AWS Cloud9.
Step 1: Set up your infrastructure
Create a file for your BeforeAllowTraffic Lambda function
Create the file for your beforeAllowTraffic hook Lambda function.
1. Create a text file and save it as beforeAllowTraffic.js in the SAM-Tutorial directory.
2. Copy the following Node.js code into beforeAllowTraffic.js. This function executes during your deployment's BeforeAllowTraffic hook.
'use strict';
const AWS = require('aws-sdk');
const codedeploy = new AWS.CodeDeploy({apiVersion: '2014-10-06'});
var lambda = new AWS.Lambda();
exports.handler = (event, context, callback) => {
console.log("Entering PreTraffic Hook!");
// Read the DeploymentId and LifecycleEventHookExecutionId from the event payload var deploymentId = event.DeploymentId;
var lifecycleEventHookExecutionId = event.LifecycleEventHookExecutionId;
var functionToTest = process.env.NewVersion;
console.log("BeforeAllowTraffic hook tests started");
console.log("Testing new function version: " + functionToTest);
// Create parameters to pass to the updated Lambda function that // include the newly added "time" option. If the function did not // update, then the "time" option is invalid and function returns // a statusCode of 400 indicating it failed.
var lambdaParams = {
FunctionName: functionToTest, Payload: "{\"option\": \"time\"}", InvocationType: "RequestResponse"
};
var lambdaResult = "Failed";
// Invoke the updated Lambda function.
lambda.invoke(lambdaParams, function(err, data) { if (err){ // an error occurred
console.log("Result: " + JSON.stringify(result));
console.log("statusCode: " + result.statusCode);
// Complete the PreTraffic Hook by sending CodeDeploy the validation status var params = {
deploymentId: deploymentId,
lifecycleEventHookExecutionId: lifecycleEventHookExecutionId, status: lambdaResult // status can be 'Succeeded' or 'Failed'
Step 1: Set up your infrastructure
};
// Pass CodeDeploy the prepared validation test results.
codedeploy.putLifecycleEventHookExecutionStatus(params, function(err, data) { if (err) {
// Validation failed.
console.log("CodeDeploy Status update failed");
console.log(err, err.stack);
callback("CodeDeploy Status update failed");
} else {
// Validation succeeded.
console.log("CodeDeploy status updated successfully");
callback(null, "CodeDeploy status updated successfully");
} });
} });
}
Create a file for your AfterAllowTraffic Lambda function
Create the file for your afterAllowTraffic hook Lambda function.
1. Create a text file and save it as afterAllowTraffic.js in the SAM-Tutorial directory.
2. Copy the following Node.js code into afterAllowTraffic.js. This function executes during your deployment's AfterAllowTraffic hook.
'use strict';
const AWS = require('aws-sdk');
const codedeploy = new AWS.CodeDeploy({apiVersion: '2014-10-06'});
var lambda = new AWS.Lambda();
exports.handler = (event, context, callback) => { console.log("Entering PostTraffic Hook!");
// Read the DeploymentId and LifecycleEventHookExecutionId from the event payload var deploymentId = event.DeploymentId;
var lifecycleEventHookExecutionId = event.LifecycleEventHookExecutionId;
var functionToTest = process.env.NewVersion;
console.log("AfterAllowTraffic hook tests started");
console.log("Testing new function version: " + functionToTest);
// Create parameters to pass to the updated Lambda function that // include the original "date" parameter. If the function did not // update as expected, then the "date" option might be invalid. If // the parameter is invalid, the function returns
// a statusCode of 400 indicating it failed.
var lambdaParams = {
FunctionName: functionToTest,
Payload: "{\"option\": \"date\", \"period\": \"today\"}", InvocationType: "RequestResponse"
};
var lambdaResult = "Failed";
// Invoke the updated Lambda function.
Step 1: Set up your infrastructure
}
else{ // successful response
var result = JSON.parse(data.Payload);
console.log("Result: " + JSON.stringify(result));
console.log("statusCode: " + result.statusCode);
lifecycleEventHookExecutionId: lifecycleEventHookExecutionId, status: lambdaResult // status can be 'Succeeded' or 'Failed' };
// Pass CodeDeploy the prepared validation test results.
codedeploy.putLifecycleEventHookExecutionStatus(params, function(err, data) { if (err) {
// Validation failed.
console.log("CodeDeploy Status update failed");
console.log(err, err.stack);
callback("CodeDeploy Status update failed");
} else {
// Validation succeeded.
console.log("CodeDeploy status updated successfully");
callback(null, "CodeDeploy status updated successfully");
} });
} });
}
Package the AWS SAM application
You should now have four files in your SAM-Tutorial directory:
• beforeAllowTraffic.js
• afterAllowTraffic.js
• myDateTimeFunction.js
• template.yml
You are now ready to use the AWS SAM sam package command to create and package artifacts for your Lambda functions and CodeDeploy application. The artifacts are uploaded to an S3 bucket. The output of the command is a new file called package.yml. This file is used by the AWS SAM sam deploy command in the next step.
NoteFor more information on the sam package command, see AWS SAM CLI command reference in the AWS Serverless Application Model Developer Guide.
In the SAM-Tutorial directory, run the following.
Step 1: Set up your infrastructure
sam package \
--template-file template.yml \ --output-template-file package.yml \ --s3-bucket your-S3-bucket
For the s3-bucket parameter, specify the Amazon S3 bucket you created as a prerequisite for this tutorial. The output-template-file specifies the name of the new file that is used by the AWS SAM sam deploy command.
Deploy the AWS SAM application
Use the AWS SAM sam deploy command with the package.yml file to create your Lambda functions and CodeDeploy application and deployment group using AWS CloudFormation.
NoteFor more information on the sam deploy command, see AWS SAM CLI command reference in the AWS Serverless Application Model Developer Guide.
In the SAM-Tutorial directory, run the following command.
sam deploy \
--template-file package.yml \ --stack-name my-date-time-app \ --capabilities CAPABILITY_IAM
The --capabilities CAPABILITY_IAM parameter is required to authorize AWS CloudFormation to create IAM roles.
(Optional) inspect and test your infrastructure
This topic shows how to view your infrastructure components and test your Lambda function.
To see the result of your stack after you run sam deploy
1. Open the AWS CloudFormation console at https://console.aws.amazon.com/cloudformation.
2. In the navigation pane, choose Stacks. The my-date-time-app stack appears at the top.
3. Choose the Events tab to see which events are complete. You can view the events while the stack creation is in progress. When creation of the stack is complete, you can see all stack creation events.
4. With your stack selected, choose Resources. In the Type column, you can see your Lambda functions, myDateTimeFunction, CodeDeployHook_beforeAllowTraffic, and CodeDeployHook_afterAllowTraffic. The Physical ID column of each of your Lambda functions contains a link to view the functions in the Lambda console.
NoteThe name of the myDateTimeFunction Lambda function is prepended with the name of the AWS CloudFormation stack and has an identifier added to it, so it looks like my-date-time-app-myDateTimeFunction-123456ABCDEF.
5. Open the CodeDeploy console at https://console.aws.amazon.com/codedeploy/.
6. In the navigation pane, expand Deploy, and then choose Applications.
7. You should see a new CodeDeploy application created by AWS CloudFormation with a name that starts with my-date-time-app-ServerlessDeploymentApplication. Choose this application.
8. You should see a deployment group with a name that starts with
my-date-time-app-Step 2: Update the Lambda function
(Optional) to test your function (console)
1. Open the AWS Lambda console at https://console.aws.amazon.com/lambda/.
2. From the navigation pane, choose your my-date-time-app-myDateTimeFunction function. In the console, its name contains an identifier, so it looks like my-date-time-app-myDateTimeFunction-123456ABCDEF.
3. Choose Test.
4. In Event name, enter a name for your test event.
5. Enter the following for your test event, and then choose Create.
{ "option": "date", "period": "today"
}
6. Choose Test. You should see only your test event in the list of test events.
For Execution result, you should see succeeded.
7. Under Execution result, expand Details to see the results. You should see the current month, day, and year.
(Optional) to test your function (AWS CLI)
1. Locate the ARN of your Lambda function. It appears at the top of the Lambda console when you are viewing your function.
2. Run the following command. Replace your-function-arn with the function ARN.
aws lambda invoke \
--function your-function-arn \
--cli-binary-format raw-in-base64-out \
--payload "{\"option\": \"date\", \"period\": \"today\"}" out.txt 3. Open out.txt to confirm the result contains the current month, day, and year.
Step 2: Update the Lambda function
In this topic, you update your myDateTimeFunction.js file. In the next step, you use the file to deploy the updated function. This triggers CodeDeploy to deploy it by shifting production traffic from the current version of the Lambda function to the updated version.
To update your Lambda function 1. Open myDateTimeFunction.js.
2. Remove the two comment markers ("/*" and "*/") and the explanatory text at the start and end of the case named time in the switch block.
The uncommented code lets you pass a new parameter, time, to the function. If you pass time to the updated function, it returns the current hour, minute, and second.
3. Save myDateTimeFunction.js. It should look like the following:
'use strict';
exports.handler = function(event, context, callback) {
Step 2: Update the Lambda function
if (event.body) {
event = JSON.parse(event.body);
}
var sc; // Status code
var result = ""; // Response payload switch(event.option) {
headers: { "Content-type": "application/json" }, body: JSON.stringify( result )
};
callback(null, response);
function setDateResult(option) {
Step 3: Deploy the updated Lambda function
var y; // Year switch(option) { case "yesterday":
d.setDate(d.getDate() - 1);
break;
case "tomorrow":
d.setDate(d.getDate() + 1);
default:
break;
}
mo = d.getMonth() + 1; // Months are zero offset (0-11) da = d.getDate();
y = d.getFullYear();
result = { "month": mo, "day": da, "year": y };
return result;
} };
Step 3: Deploy the updated Lambda function
In this step, you use your updated myDateTimeFunction.js to update and initiate the deployment of your Lambda function. You can monitor the deployment progress in the CodeDeploy or AWS Lambda console.
The AutoPublishAlias: live line in your AWS SAM template causes your infrastructure to detect updates to functions that use the live alias. An update to your function triggers a deployment by CodeDeploy that shifts production traffic from the original version of the function to the updated version.
The sam package and sam deploy commands are used to update and trigger the deployment of your Lambda function. You executed these commands in Package the AWS SAM application (p. 151) and Deploy the AWS SAM application (p. 152).
To deploy your updated Lambda function
1. In the SAM-Tutorial directory, run the following command.
sam package \
--template-file template.yml \ --output-template-file package.yml \ --s3-bucket your-S3-bucket
This creates a new set of artifacts that reference your updated Lambda function in your S3 bucket.
2. In the SAM-Tutorial directory, run the following command.
sam deploy \
--template-file package.yml \ --stack-name my-date-time-app \ --capabilities CAPABILITY_IAM
Step 3: Deploy the updated Lambda function
Because the stack name is still my-date-time-app, AWS CloudFormation recognizes that this is a stack update. To view your updated stack, return the AWS CloudFormation console, and from the navigation pane, choose Stacks.
(Optional) to view traffic during a deployment (CodeDeploy console) 1. Open the CodeDeploy console at https://console.aws.amazon.com/codedeploy/.
2. In the navigation pane, expand Applications, and then choose your my-date-time-app-ServerlessDeploymentApplication application.
3. In Deployment groups, choose your application's deployment group. Its status should be In progress.
4. In Deployment group history, choose the deployment that is in progress.
The Traffic shifting progress bar and the percentages in the Original and Replacement boxes on this page display its progress.
(Optional) to view traffic during a deployment (Lambda console)
1. Open the AWS Lambda console at https://console.aws.amazon.com/lambda/.
2. From the navigation pane, choose your my-date-time-app-myDateTimeFunction function. In the console, its name contains an identifier, so it looks like my-date-time-app-myDateTimeFunction-123456ABCDEF.
3. Choose Aliases, and then choose live.
The weights next to your original function version (version 1) and your updated function version (version 2) show how much traffic is served to each version at the time this AWS Lambda console page was loaded. The page does not update the weights over time. If you refresh the page once a minute, the weight for version 1 decreases by 10 percent and the weight for version 2 increases by 10 percent until
Step 4: View your deployment results
Step 4: View your deployment results
In this step, you view the results of your deployment. If your deployment succeeds, you can confirm that your updated Lambda function receives production traffic. If your deployment fails, you can use CloudWatch Logs to view the output of the validation tests in the Lambda function that run during your deployment's lifecycle hoooks.
Topics
• Test your deployed function (p. 157)
• View hook events in CloudWatch Logs (p. 158)
Test your deployed function
The sam deploy command updates the my-date-time-app-myDateTimeFunction Lambda function.
The function version is updated to 2 and added to the live alias.
To see the update in the Lambda console
1. Open the AWS Lambda console at https://console.aws.amazon.com/lambda/.
2. From the navigation pane, choose the my-date-time-app-myDateTimeFunction
function. In the console, its name contains an identifier, so it looks like my-date-time-app-myDateTimeFunction-123456ABCDEF.
3. Choose Qualifiers, and then choose Aliases. After the deployment is complete (approximately 10 minutes), for the live alias, you should see Version: 2.
Step 4: View your deployment results
4. In Function code, view the source code for your function. Your changes should appear.
5. (Optional) You can use the test instructions in Step 2: Update the Lambda function (p. 153) to test your updated function. Create a new test event with the following payload, and then confirm the result contains the current hour, minute, and second.
{ "option": "time"
}
To use the AWS CLI to test your updated function, run the following command, and then open out.txt to confirm the result contains the current hour, minute, and second.
aws lambda invoke --function your-function-arn --payload "{\"option\": \"time\"}"
out.txt
NoteIf you use the AWS CLI to test your function before the deployment is complete, you might receive unexpected results. This is because CodeDeploy incrementally shifts 10 percent of traffic to the updated version every minute. During the deployment, some traffic still points to the original version, so aws lambda invoke might use the original version. After 10 minutes, the deployment is complete and all traffic points to the new version of the function.
View hook events in CloudWatch Logs
During the BeforeAllowTraffic hook, CodeDeploy executes your
CodeDeployHook_beforeAllowTraffic Lambda function. During the AfterAllowTraffic hook, CodeDeploy executes your CodeDeployHook_afterAllowTraffic Lambda function. Each function runs a validation test that invokes the updated version of your function using the new time parameter.
CodeDeployHook_beforeAllowTraffic Lambda function. During the AfterAllowTraffic hook, CodeDeploy executes your CodeDeployHook_afterAllowTraffic Lambda function. Each function runs a validation test that invokes the updated version of your function using the new time parameter.