
Deploying Lambda Functions Safely: SAM, CodeDeploy, Canary Strategies, and Automatic Rollback
Learn three ways to deploy AWS Lambda functions safely with gradual traffic shifting and automatic rollback: raw CodeDeploy for the mechanics, SAM DeploymentPreference for real-world automation, and CodePipeline V2's native Lambda deploy action. Covers versions, aliases, routing weights, canary and linear strategies, pre-traffic hooks, and CloudWatch alarm-based rollback.
Lambda deployments are unlike anything else on AWS. No servers to manage, no agents to install, no files to be copied — deployment means publishing a new version of your function and shifting traffic to it. The risk: without safeguards, traffic shifts are instantaneous and all-or-nothing. One broken version = 100% of traffic affected. The solution is gradual traffic shifting with validation and automatic rollback.
In this post we'll take a look at three ways to do this: raw CodeDeploy, SAM
DeploymentPreference , and CodePipeline V2's native Lambda deploy action.Prerequisites
To follow along, you'll need:
- AWS CLI v2 installed and configured with credentials that have permissions for Lambda, IAM, CodeDeploy, and CloudWatch
- AWS SAM CLI installed
- An AWS account
- Node.js 20+ (for the Lambda function and hook code)
Lambda Versions, Aliases, and Routing Weights
Before getting into deployment strategies, you need to understand three primitives.
Versions are immutable snapshots of your function's code and configuration. Once published, a version never changes. Each version gets a numeric identifier (1, 2, 3...) and its own ARN.
Aliases are named pointers to a version. For example, an alias called
live might point to version 5. Consumers invoke the alias ARN instead of a specific version — this gives you a stable endpoint that you can retarget without updating callers.Routing config is the mechanism that makes gradual deployments possible. An alias can split traffic between two versions using
AdditionalVersionWeights . For example, you can route 90% of invocations to version 1 and 10% to version 2.This is the primitive that CodeDeploy uses — it adjusts
AdditionalVersionWeights over time, gradually shifting traffic from the old version to the new one.Approach 1 — Raw CodeDeploy (Understanding the Mechanics)
Using CodeDeploy directly gives you full visibility into how Lambda traffic shifting works. This approach has more moving parts than SAM, but understanding it makes everything else click.
Setup
Start by creating an IAM execution role for the Lambda function. The role grants basic permissions (CloudWatch Logs) via the
AWSLambdaBasicExecutionRole managed policy:# Create the execution role — Lambda needs this to write logsaws iam create-role \ --role-name lambda-deploy-lab-role \ --assume-role-policy-document '{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Principal": {"Service": "lambda.amazonaws.com"}, "Action": "sts:AssumeRole" }] }'
# Attach the basic execution policy (CloudWatch Logs access)aws iam attach-role-policy \ --role-name lambda-deploy-lab-role \ --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
# Store the role ARN for later useROLE_ARN=$(aws iam get-role --role-name lambda-deploy-lab-role \ --query 'Role.Arn' --output text)Write a minimal Lambda handler that returns a version identifier in the response. This version field is what the pre-traffic hook will validate later:
mkdir -p lambda-deploy-lab && cd lambda-deploy-lab
cat > index.mjs << 'EOF'export const handler = async (event) => { return { statusCode: 200, // The "version" field lets the pre-traffic hook verify which version is responding body: JSON.stringify({ version: "1.0", message: "Hello from v1" }) };};EOF
# Bundle into a zip — Lambda requires deployment packages as archiveszip function.zip index.mjsCreate the function and immediately publish version 1. Publishing freezes the current code and config into an immutable snapshot:
# Create the function from the zip bundleaws lambda create-function \ --function-name deploy-lab-function \ --runtime nodejs20.x \ --handler index.handler \ --role $ROLE_ARN \ --zip-file fileb://function.zip
# Publish version 1 — creates an immutable snapshot of the current codeaws lambda publish-version \ --function-name deploy-lab-function \ --query 'Version' --output text# Returns: 1Create the
live alias pointing to version 1. Consumers will invoke this alias — it provides a stable ARN that you retarget during deployments:# Create alias "live" → version 1 (consumers invoke the alias, not a version number)aws lambda create-alias \ --function-name deploy-lab-function \ --name live \ --function-version 1Now let's test our alias:
# Invoke the function through the "live" alias to verify the setupaws lambda invoke --function-name deploy-lab-function --qualifier live \ --output text /dev/stdout 2>/dev/null | jq .
# Expected: {"statusCode":200,"body":"{\"version\":\"1.0\",\"message\":\"Hello from v1\"}"}Next, let's create the CodeDeploy resources. CodeDeploy needs its own service role (with permissions to modify Lambda aliases) and an application configured for the Lambda compute platform:
# CodeDeploy service role — allows CodeDeploy to manipulate Lambda aliasesaws iam create-role \ --role-name codedeploy-lambda-role \ --assume-role-policy-document '{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Principal": {"Service": "codedeploy.amazonaws.com"}, "Action": "sts:AssumeRole" }] }'
# This managed policy grants: lambda:UpdateAlias, lambda:GetAlias,# lambda:GetProvisionedConcurrencyConfig, cloudwatch:DescribeAlarms, sns:Publish,# and lambda:InvokeFunction ONLY on functions matching "CodeDeployHook_*"aws iam attach-role-policy \ --role-name codedeploy-lambda-role \ --policy-arn arn:aws:iam::aws:policy/service-role/AWSCodeDeployRoleForLambda
CODEDEPLOY_ROLE=$(aws iam get-role --role-name codedeploy-lambda-role \ --query 'Role.Arn' --output text)
# Create the CodeDeploy application — must specify Lambda as the compute platformaws deploy create-application \ --application-name lambda-deploy-lab \ --compute-platform Lambda
# Create deployment group with canary strategy: 10% traffic for 5 minutes, then 100%# Lambda deployments are always BLUE_GREEN with traffic controlaws deploy create-deployment-group \ --application-name lambda-deploy-lab \ --deployment-group-name canary-group \ --service-role-arn $CODEDEPLOY_ROLE \ --deployment-config-name CodeDeployDefault.LambdaCanary10Percent5Minutes \ --deployment-style deploymentType=BLUE_GREEN,deploymentOption=WITH_TRAFFIC_CONTROLThe AppSpec File for Lambda
The Lambda AppSpec has a different structure than EC2. It declares which function, alias, and versions are involved, plus optional hooks that reference other Lambda functions for validation.
# appspec.yamlversion: 0.0Resources: - deploy-lab-function: Type: AWS::Lambda::Function Properties: Name: deploy-lab-function # The function to deploy Alias: live # The alias CodeDeploy will shift traffic on CurrentVersion: 1 # Where traffic is now TargetVersion: 2 # Where traffic should goHooks: # Reference a Lambda function by name — CodeDeploy invokes it before traffic shifts - BeforeAllowTraffic: CodeDeployHook_deploy-lab-pretrafficKey differences from EC2 AppSpec:
-
Resourcesnames the function, alias, and both versions (current and target)
-
Hooksreferences Lambda function names — not script files on disk
- Only two hook events exist:
BeforeAllowTrafficandAfterAllowTraffic
Important: TheAWSCodeDeployRoleForLambdamanaged policy only grantslambda:InvokeFunctionon functions matchingCodeDeployHook_*. Hook functions must use this prefix or you'll get a permissions error when CodeDeploy tries to invoke them.
The Pre-Traffic Hook Function
The hook is a separate Lambda function that CodeDeploy invokes before shifting any traffic. It must:
- Invoke the new version
- Validate the response
- Report success or failure back to CodeDeploy by calling
PutLifecycleEventHookExecutionStatus
cat > pretraffic-hook.mjs << 'EOF'import { LambdaClient, InvokeCommand } from "@aws-sdk/client-lambda";import { CodeDeployClient, PutLifecycleEventHookExecutionStatusCommand } from "@aws-sdk/client-codedeploy";
const lambda = new LambdaClient();const codedeploy = new CodeDeployClient();
export const handler = async (event) => { // CodeDeploy passes these identifiers — needed to report back the hook result const deploymentId = event.DeploymentId; const lifecycleEventHookExecutionId = event.LifecycleEventHookExecutionId;
// Default to Failed — only set Succeeded if validation passes let status = "Failed";
try { console.log("Validating new version:", process.env.NEW_VERSION);
const result = await lambda.send(new InvokeCommand({ FunctionName: process.env.TARGET_FUNCTION, InvocationType: "RequestResponse", Qualifier: process.env.NEW_VERSION, }));
const payload = JSON.parse(Buffer.from(result.Payload).toString()); const body = JSON.parse(payload.body);
// Validate — check that the response has the expected structure if (payload.statusCode === 200 && body.version) { console.log("Validation passed:", body); status = "Succeeded"; } else { console.error("Validation failed — unexpected response:", payload); } } catch (err) { // Catches invocation errors (e.g., function doesn't exist, timeout) console.error("Validation failed — invocation error:", err); }
// Step 3: Report result to CodeDeploy — this determines whether traffic shifts proceed await codedeploy.send(new PutLifecycleEventHookExecutionStatusCommand({ deploymentId, lifecycleEventHookExecutionId, status, }));
return { statusCode: 200, body: status };};EOF
zip pretraffic-hook.zip pretraffic-hook.mjsDeploy the hook function. It needs its own execution role with permissions to invoke the target Lambda function and to report lifecycle status back to CodeDeploy:
# Create execution role for the hook functionaws iam create-role \ --role-name lambda-hook-role \ --assume-role-policy-document '{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Principal": {"Service": "lambda.amazonaws.com"}, "Action": "sts:AssumeRole" }] }'
# Basic execution permissions (CloudWatch Logs)aws iam attach-role-policy \ --role-name lambda-hook-role \ --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
# The hook needs two additional permissions:# 1. lambda:InvokeFunction — to call the new version and validate it# 2. codedeploy:PutLifecycleEventHookExecutionStatus — to report pass/failaws iam put-role-policy \ --role-name lambda-hook-role \ --policy-name hook-permissions \ --policy-document '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "lambda:InvokeFunction", "Resource": "*" }, { "Effect": "Allow", "Action": "codedeploy:PutLifecycleEventHookExecutionStatus", "Resource": "*" } ] }'
# Save the Hook's function ARN for laterHOOK_ROLE_ARN=$(aws iam get-role --role-name lambda-hook-role \ --query 'Role.Arn' --output text)
# Create the hook function with a 60-second timeout (gives it time to invoke + validate)aws lambda create-function \ --function-name CodeDeployHook_deploy-lab-pretraffic \ --runtime nodejs20.x \ --handler pretraffic-hook.handler \ --role $HOOK_ROLE_ARN \ --zip-file fileb://pretraffic-hook.zip \ --timeout 60 \ --environment "Variables={TARGET_FUNCTION=deploy-lab-function}"If the hook reports
Failed , CodeDeploy rolls back immediately — no traffic ever reaches the new version.Deploy with Canary
Update the function code to return version 2.0, then publish it as a new immutable version:
# Change the return version in the functioncat > index.mjs << 'EOF'export const handler = async (event) => { return { statusCode: 200, body: JSON.stringify({ version: "2.0", message: "Hello from v2" }) };};EOF
# ZIP the functionzip function.zip index.mjs
# Update the function's $LATEST codeaws lambda update-function-code \ --function-name deploy-lab-function \ --zip-file fileb://function.zip
# Wait for the update to propagate (required before publishing)aws lambda wait function-updated --function-name deploy-lab-function
# Publish version 2 — this is the version CodeDeploy will shift traffic to.# Capture the version number so we can point the hook at it.NEW_VERSION=$(aws lambda publish-version \ --function-name deploy-lab-function \ --query 'Version' --output text)echo "Published version: $NEW_VERSION" # 2Point the hook at the version being deployed. This is the step that makes the hook validate the new version rather than whatever the alias currently points at:
# Tell the hook which version to validate during BeforeAllowTrafficaws lambda update-function-configuration \ --function-name CodeDeployHook_deploy-lab-pretraffic \ --environment "Variables={TARGET_FUNCTION=deploy-lab-function,NEW_VERSION=$NEW_VERSION}"
# Wait for the config update to settle before deployingaws lambda wait function-updated --function-name CodeDeployHook_deploy-lab-pretrafficTrigger the deployment. For Lambda, CodeDeploy accepts the AppSpec as inline JSON content:
# Create the deployment — AppSpec is passed inline as JSON matching the structure shown aboveDEPLOY_ID=$(aws deploy create-deployment \ --application-name lambda-deploy-lab \ --deployment-group-name canary-group \ --revision '{"revisionType": "AppSpecContent", "appSpecContent": {"content": "{\"version\": 0.0, \"Resources\": [{\"deploy-lab-function\": {\"Type\": \"AWS::Lambda::Function\", \"Properties\": {\"Name\": \"deploy-lab-function\", \"Alias\": \"live\", \"CurrentVersion\": \"1\", \"TargetVersion\": \"2\"}}}], \"Hooks\": [{\"BeforeAllowTraffic\": \"CodeDeployHook_deploy-lab-pretraffic\"}]}"}}' \ --query 'deploymentId' --output text)
echo "Deployment: $DEPLOY_ID"Poll the deployment status until it completes. The canary phase lasts 5 minutes — during that time, 10% of traffic hits version 2:
# Poll deployment status every 10 seconds until it finisheswhile true; do STATUS=$(aws deploy get-deployment --deployment-id $DEPLOY_ID \ --query 'deploymentInfo.status' --output text) echo "$(date +%H:%M:%S) $STATUS" # Exit loop when deployment is no longer in progress if [ "$STATUS" != "InProgress" ] && [ "$STATUS" != "Created" ]; then break; fi sleep 10doneDuring the canary phase, inspect the alias to see the traffic split. The
RoutingConfig field shows how traffic is distributed between versions:# Check the alias routing configuration — shows the weight split between versionsaws lambda get-alias \ --function-name deploy-lab-function \ --name live \ --query '{Version: FunctionVersion, RoutingConfig: RoutingConfig}'You'll see
AdditionalVersionWeights showing 10% routed to version 2. Invoke the function 20 times to observe the traffic split in action — roughly 18 calls will hit v1 and 2 will hit v2:# Invoke 20 times via the alias and tally which version respondsfor i in $(seq 1 20); do aws lambda invoke --function-name deploy-lab-function --qualifier live \ /tmp/lambda-response.json > /dev/null 2>&1 jq -r '.body | fromjson | .version' /tmp/lambda-response.jsondone | sort | uniq -c# Expected: ~18 responses from "1.0", ~2 from "2.0"After 5 minutes, the canary period completes and the alias shifts 100% to version 2.
Automatic Rollback
Safe deployments rely on two layers of protection, but they are not equals:
- Pre-traffic hooks (the primary gate) — validate the new version before any traffic shifts. If the hook fails, CodeDeploy rolls back immediately and no user ever touches the new version. This is the layer you control directly and can test deterministically.
- CloudWatch alarms (the backstop) — watch runtime metrics during traffic shifting. They catch problems the hook can't see: issues that only appear under real load, or non-functional regressions like latency, throttling, or memory pressure. They are essential, but they're reactive — they act after some traffic has already reached the new version.
We'll demonstrate the hook doing its job, then wire up the alarm as the supporting layer.
The hook catches a broken deploy
Deploy a version that's outright broken — it throws on every invocation:
# A deliberately broken handler — every invocation throwscat > index.mjs << 'EOF'export const handler = async (event) => { throw new Error("Intentionally broken for rollback demo");};EOF
zip function.zip index.mjs
# Update, wait, and publish version 3aws lambda update-function-code --function-name deploy-lab-function --zip-file fileb://function.zipaws lambda wait function-updated --function-name deploy-lab-functionNEW_VERSION=$(aws lambda publish-version --function-name deploy-lab-function \ --query 'Version' --output text)echo "Published version: $NEW_VERSION" # 3
# Point the hook at v3 so it validates the new (broken) versionaws lambda update-function-configuration \ --function-name CodeDeployHook_deploy-lab-pretraffic \ --environment "Variables={TARGET_FUNCTION=deploy-lab-function,NEW_VERSION=$NEW_VERSION}"aws lambda wait function-updated --function-name CodeDeployHook_deploy-lab-pretrafficTrigger the deployment. During
BeforeAllowTraffic , the hook invokes v3, the invocation throws, the hook reports Failed , and CodeDeploy aborts before shifting any traffic:# Trigger deployment — the hook will invoke v3, it throws, the hook fails the deploymentDEPLOY_ID=$(aws deploy create-deployment \ --application-name lambda-deploy-lab \ --deployment-group-name canary-group \ --revision '{"revisionType": "AppSpecContent", "appSpecContent": {"content": "{\"version\": 0.0, \"Resources\": [{\"deploy-lab-function\": {\"Type\": \"AWS::Lambda::Function\", \"Properties\": {\"Name\": \"deploy-lab-function\", \"Alias\": \"live\", \"CurrentVersion\": \"2\", \"TargetVersion\": \"3\"}}}], \"Hooks\": [{\"BeforeAllowTraffic\": \"CodeDeployHook_deploy-lab-pretraffic\"}]}"}}' \ --query 'deploymentId' --output text)
echo "Deployment: $DEPLOY_ID"
# Poll — expect BeforeAllowTraffic to fail, then the deployment to roll backwhile true; do STATUS=$(aws deploy get-deployment --deployment-id $DEPLOY_ID \ --query 'deploymentInfo.status' --output text) echo "$(date +%H:%M:%S) $STATUS" if [ "$STATUS" != "InProgress" ] && [ "$STATUS" != "Created" ]; then break; fi sleep 10doneThe deployment reaches
Failed (or Stopped ) within seconds — no five-minute canary wait, no traffic generator, no timing games. The live alias never leaves version 2. Confirm it:# The alias should still point at version 2 — v3 never received any trafficaws lambda get-alias --function-name deploy-lab-function --name live \ --query '{Version: FunctionVersion, RoutingConfig: RoutingConfig}'This is the whole point of a pre-traffic hook: a broken version is caught and rejected before it can affect a single request. Because we corrected the hook to validate the new version (not the alias), it actually sees v3's failure — the original alias-invoking version would have validated the healthy v2 and waved this broken deploy straight through.
Wiring up the alarm as a backstop
The hook can only catch what a synthetic invocation reveals. Some failures — a latency regression, elevated error rates under concurrency, memory pressure — only show up once real traffic flows. That's what the CloudWatch alarm layer is for. You attach an alarm to the deployment group, and CodeDeploy rolls back if it fires during traffic shifting:
# Create an alarm on the function's error count, scoped to the live aliasaws cloudwatch put-metric-alarm \ --alarm-name deploy-lab-errors \ --namespace AWS/Lambda \ --metric-name Errors \ --statistic Sum \ --period 60 \ --threshold 1 \ --comparison-operator GreaterThanOrEqualToThreshold \ --evaluation-periods 1 \ --treat-missing-data notBreaching \ --dimensions Name=FunctionName,Value=deploy-lab-function Name=Resource,Value=deploy-lab-function:live
# Attach the alarm to the deployment group and enable auto-rollbackaws deploy update-deployment-group \ --application-name lambda-deploy-lab \ --current-deployment-group-name canary-group \ --alarm-configuration enabled=true,alarms=[{name=deploy-lab-errors}] \ --auto-rollback-configuration enabled=true,events=DEPLOYMENT_FAILURE,DEPLOYMENT_STOP_ON_ALARMWith this in place, a deployment that passes the hook but misbehaves under canary traffic will trip the alarm and roll back automatically.
Approach 2 — SAM DeploymentPreference (The Real-World Workflow)
Serverless Application Model (SAM) automates everything from the previous section:
-
AutoPublishAliasdetects code changes, publishes a new version, and creates/updates the alias
-
DeploymentPreferencecreates the CodeDeploy application, deployment group, and triggers the deployment
-
Alarmsattaches CloudWatch alarms to the deployment group
-
Hookswires pre/post-traffic validation functions
Complete SAM Workflow
Create the project directory:
mkdir -p sam-deploy-lab/src && cd sam-deploy-labThe SAM template below defines: the main function with
AutoPublishAlias and DeploymentPreference , a pre-traffic hook function with the required CodeDeployHook_ prefix, and a CloudWatch alarm for runtime error detection:template.yaml :AWSTemplateFormatVersion: '2010-09-09'Transform: AWS::Serverless-2016-10-31Description: Lambda safe deployment with SAM DeploymentPreference
Globals: Function: Runtime: nodejs20.x Timeout: 10
Resources: # Main function — AutoPublishAlias creates/updates the "live" alias on each deploy MyFunction: Type: AWS::Serverless::Function Properties: FunctionName: sam-deploy-lab-function Handler: src/app.handler AutoPublishAlias: live # SAM auto-publishes a new version and updates this alias DeploymentPreference: Type: Canary10Percent5Minutes # 10% traffic for 5 min, then 100% Alarms: - !Ref FunctionErrorsAlarm # Rollback if this alarm fires during deployment Hooks: PreTraffic: !Ref PreTrafficHook # Validate before any traffic shifts
# Hook function — must start with "CodeDeployHook_" for SAM's auto-generated IAM to work PreTrafficHook: Type: AWS::Serverless::Function Properties: FunctionName: CodeDeployHook_sam-deploy-lab-pretraffic Handler: src/pretraffic.handler Policies: - Version: '2012-10-17' Statement: - Effect: Allow Action: - codedeploy:PutLifecycleEventHookExecutionStatus Resource: '*' - Effect: Allow Action: - lambda:InvokeFunction Resource: !Sub '${MyFunction.Arn}:*' - Effect: Allow Action: - lambda:ListVersionsByFunction # Resolve which version is being deployed Resource: !GetAtt MyFunction.Arn Environment: Variables: TARGET_FUNCTION: !Ref MyFunction # Resolves to the function name
# Alarm — triggers automatic rollback if errors occur during canary FunctionErrorsAlarm: Type: AWS::CloudWatch::Alarm Properties: AlarmName: sam-deploy-lab-errors Namespace: AWS/Lambda MetricName: Errors Statistic: Sum Period: 60 EvaluationPeriods: 1 Threshold: 1 ComparisonOperator: GreaterThanOrEqualToThreshold Dimensions: - Name: FunctionName Value: !Ref MyFunction - Name: Resource Value: !Sub '${MyFunction}:live' # Scoped to the alias, not $LATESTNote: SAM requires hook function names to start withCodeDeployHook_. This prefix is added to the IAM permissions that SAM's auto-generated CodeDeploy role uses.
Now let's create the Lambda main function:
src/app.mjs — the main function, identical to the v1 we used in the raw CodeDeploy section:export const handler = async (event) => { return { statusCode: 200, // Same version field the hook validates against body: JSON.stringify({ version: "1.0", message: "Hello from SAM v1" }), };};src/pretraffic.mjs — the hook function. In the raw section we passed the exact version number to the hook as an env var, because we controlled publish-version ourselves. Here SAM owns publishing, so we don't know the version number at template time. Instead the hook resolves the newest published version at runtime with ListVersionsByFunction and invokes that version (not the alias, which still points at the old version during BeforeAllowTraffic ). The function name comes from an environment variable injected by SAM:import { LambdaClient, InvokeCommand, ListVersionsByFunctionCommand } from "@aws-sdk/client-lambda";import { CodeDeployClient, PutLifecycleEventHookExecutionStatusCommand } from "@aws-sdk/client-codedeploy";
const lambda = new LambdaClient();const codedeploy = new CodeDeployClient();
// Resolve the highest-numbered published version — that's the one being deployedconst getNewestVersion = async (functionName) => { let versions = []; let marker; do { const page = await lambda.send(new ListVersionsByFunctionCommand({ FunctionName: functionName, Marker: marker, })); versions.push(...page.Versions); marker = page.NextMarker; } while (marker);
return versions .map((v) => v.Version) .filter((v) => v !== "$LATEST") .map(Number) .sort((a, b) => b - a)[0] .toString();};
export const handler = async (event) => { // CodeDeploy passes these identifiers for reporting back const deploymentId = event.DeploymentId; const lifecycleEventHookExecutionId = event.LifecycleEventHookExecutionId; let status = "Failed";
try { // Function name comes from the env var set in template.yaml const functionName = process.env.TARGET_FUNCTION;
// Invoke the NEW version directly — the alias still points at the old // version during BeforeAllowTraffic, so validating the alias tests the // wrong code. const targetVersion = await getNewestVersion(functionName); console.log("Validating new version:", targetVersion);
const result = await lambda.send(new InvokeCommand({ FunctionName: functionName, InvocationType: "RequestResponse", Qualifier: targetVersion, }));
const payload = JSON.parse(Buffer.from(result.Payload).toString()); const body = JSON.parse(payload.body);
// Validate: check for expected response structure if (payload.statusCode === 200 && body.version) { console.log("Validation passed:", body); status = "Succeeded"; } else { console.error("Validation failed:", payload); } } catch (err) { console.error("Hook invocation error:", err); }
// Report pass/fail to CodeDeploy — determines whether traffic shift proceeds await codedeploy.send(new PutLifecycleEventHookExecutionStatusCommand({ deploymentId, lifecycleEventHookExecutionId, status, }));
return { statusCode: 200, body: status };};Deploy and Observe
Build and deploy the stack for the first time. The
--guided flag walks you through configuration (stack name, region, IAM confirmation):# Build resolves dependencies and prepares deployment artifactssam build
# First deploy uses --guided to set stack name, region, and confirm IAM resource creationsam deploy --guided# Stack name: sam-deploy-lab# Confirm changes, allow IAM role creationNow change the function code and redeploy. SAM detects the code change, publishes a new version, and triggers a CodeDeploy canary deployment automatically:
# Bump the version string in the handlersed -i 's/1.0/2.0/' src/app.mjssed -i 's/v1/v2/' src/app.mjs
# Build and deploy — SAM handles version publishing and traffic shiftingsam build && sam deploySAM automatically publishes a new version, creates a CodeDeploy deployment, and starts the canary shift. You can observe the deployment in the CodeDeploy console.
The developer workflow is: change code →
sam deploy → everything else is automated.Available Deployment Types
Canary — shifts a percentage of traffic, waits, then shifts the rest:
-
Canary10Percent5Minutes
-
Canary10Percent10Minutes
-
Canary10Percent15Minutes
-
Canary10Percent30Minutes
Linear — shifts traffic in equal increments at regular intervals:
-
Linear10PercentEvery1Minute
-
Linear10PercentEvery2Minutes
-
Linear10PercentEvery3Minutes
-
Linear10PercentEvery10Minutes
AllAtOnce — shifts 100% immediately. No gradual deployment. Useful for non-production environments.
Custom — create a custom CodeDeploy deployment config and reference it by name in the
Type field.Approach 3 — CodePipeline V2 Lambda Deploy Action
CodePipeline V2 introduced a native Lambda deploy action (May 2025) that handles traffic shifting without a separate CodeDeploy application.
The action configuration supports:
-
FunctionName— the Lambda function to deploy
-
FunctionAlias— the alias to shift traffic on
-
DeployStrategy—AllAtOnce,Canary10Percent5Minutes,Linear10PercentEvery1Minute, etc.
-
Alarms— comma-separated CloudWatch alarm names for automatic rollback
-
PublishedTargetVersion— the version to deploy (or deploy from source artifact)
A CodePipeline V2 action declaration for Lambda deploy with canary traffic shifting. No AppSpec, no CodeDeploy application — the action handles everything internally:
# Pipeline action — deploys to the "live" alias with canary strategy# Rolls back automatically if either alarm fires during traffic shifting- Name: Deploy ActionTypeId: Category: Deploy Owner: AWS Provider: Lambda Version: '1' Configuration: FunctionName: my-function # Target Lambda function FunctionAlias: live # Alias to shift traffic on DeployStrategy: Canary10Percent5Minutes # Same strategies as CodeDeploy Alarms: my-function-errors,my-function-throttles # Comma-separated alarm names InputArtifacts: - Name: SourceArtifact # Zip with function codeCodePipeline manages the traffic shifting directly. The action updates the function code from the source artifact, publishes a new version, and shifts traffic according to the strategy.
When to use this approach: You already have a CodePipeline V2 pipeline and want fewer moving parts. The pipeline owns the deployment lifecycle.
When to use SAM instead: You manage infrastructure as code and want the deployment strategy declared alongside your function definition. SAM keeps everything in one template.
Comparison: When to Use What
Approach | Complexity | Automation Level | Best For |
|---|---|---|---|
Raw CodeDeploy | High — manual version publishing, AppSpec authoring, hook wiring | Low | Understanding mechanics, custom orchestration |
SAM DeploymentPreference | Low — ~10 lines of config | High — auto-publishes, auto-deploys | Most production workloads |
CodePipeline V2 Lambda action | Medium — pipeline config | Medium | Existing CodePipeline V2 workflows |
Clean Up
Remove all resources created during the lab. SAM resources are deleted with
sam delete , and the raw CodeDeploy resources require individual cleanup:# Delete the SAM stack (removes function, hook, alarm, CodeDeploy resources)sam delete --stack-name sam-deploy-lab
# Delete raw CodeDeploy resources from Approach 1aws deploy delete-deployment-group \ --application-name lambda-deploy-lab \ --deployment-group-name canary-groupaws deploy delete-application --application-name lambda-deploy-lab
# Delete the CloudWatch alarmaws cloudwatch delete-alarms --alarm-names deploy-lab-errors
# Delete Lambda functionsaws lambda delete-function --function-name deploy-lab-functionaws lambda delete-function --function-name CodeDeployHook_deploy-lab-pretraffic
# Delete IAM roles (must detach policies first)aws iam detach-role-policy --role-name lambda-deploy-lab-role \ --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRoleaws iam delete-role --role-name lambda-deploy-lab-role
aws iam detach-role-policy --role-name codedeploy-lambda-role \ --policy-arn arn:aws:iam::aws:policy/service-role/AWSCodeDeployRoleForLambdaaws iam delete-role --role-name codedeploy-lambda-role
aws iam delete-role-policy --role-name lambda-hook-role --policy-name hook-permissionsaws iam detach-role-policy --role-name lambda-hook-role \ --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRoleaws iam delete-role --role-name lambda-hook-roleConclusion
Lambda deployments are about controlling traffic flow between immutable versions. CodeDeploy provides the mechanics: canary/linear shifting, pre-traffic hooks, alarm-based rollback. SAM wraps CodeDeploy into a declarative experience —
AutoPublishAlias + DeploymentPreference handles everything from version publishing to traffic shifting to automatic rollback.The safety pattern has a primary gate and a backstop. The pre-traffic hook is the primary gate: it validates the new version functionally (can it handle a request?) before any traffic shifts, and it's deterministic — a broken version is rejected in seconds, and no user is ever exposed. The CloudWatch alarm is the backstop: it monitors runtime behavior during the canary window and catches what a synthetic probe can't (latency, throttling, errors that only appear under real load). The alarm is reactive and subject to evaluation lag, so lean on the hook first and treat the alarm as the safety net behind it.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article