Skip to Content
Cloud Engineering Academy
9. DevOps & CI/CD

Lambda deployments: versions, aliases and safe traffic shifting

Release a .NET 10 Lambda function the way a bank should: immutable versions, a stable alias, canary traffic through CodeDeploy, pre-traffic and post-traffic hooks written in C#, and automatic rollback on CloudWatch alarms.

intermediate⏱ 1 h 50 min🟢 FreeDOP-C02DVA-C03

Assumes: .NET 10 LTS (dotnet10 Lambda runtime) · AWS SDK for .NET v4 (AWSSDK.CodeDeploy 4.1.0.2, AWSSDK.Lambda 4.1.3) · Amazon.Lambda.Core 3.4.0 · AWS SAM CLI · Amazon.CDK.Lib 2.277.0 · Terraform AWS provider v6 · AWS CLI v2 · Region us-east-1. Verified against official sources on 2026-11-18.

Learning objectives

By the end of this lesson you can:

  • Explain the difference between $LATEST, a published version and an alias, and say why production callers must only ever invoke an alias.
  • Shift a percentage of traffic to a new version with a weighted alias, by hand with the AWS CLI, and explain the limits of doing it by hand.
  • Configure AWS CodeDeploy (through AWS SAM, CDK or Terraform) to run a canary or linear Lambda deployment that rolls back automatically when a CloudWatch alarm fires.
  • Write pre-traffic and post-traffic hooks in C# that test the new version and report the result back to CodeDeploy.
  • Plan the parts that are easy to forget: provisioned concurrency, SnapStart, event source mappings, resource policies and version clean-up.

Prerequisites

Why this matters in banking

Harbourline Bank's Payments Service validates every outgoing payment in a Lambda function called hl-m09-payment-validator. It checks the IBAN checksum, the scheme cut-off times and the daily limit before a payment moves to sanctions screening. On a Friday afternoon a developer ships a small change: a refactor of the cut-off logic for SEPA_INST. The deployment is a single aws lambda update-function-code call that overwrites the code everyone is calling. A time-zone bug makes every instant payment after 15:00 UTC fail validation. Within four minutes, customers in the mobile app see "Payment could not be sent"; within ten minutes, the contact centre queue doubles. Rolling back means finding the previous zip file, which nobody kept.

Every part of that story is avoidable with features Lambda has had for years:

  • Versions make every release immutable, so "the previous build" always exists and can be pointed at in seconds.
  • Aliases give callers a stable name (live) so that a release is just "move the alias", not "change every caller".
  • Weighted aliases and CodeDeploy send only 10% of payments to the new code first, and watch an alarm while they do.
  • Hooks let you run a synthetic payment through the new version before any customer reaches it.

For a bank, these are not just engineering niceties. They are what you show a change-advisory board when it asks "what is your back-out plan and how long does it take?" The honest answer becomes "the alarm triggers rollback automatically, typically within a minute or two of the alarm firing, and here is the deployment record that proves it happened."

The idea in plain language

A Lambda function has three kinds of "name" you can call:

  • $LATEST — the editable working copy. Every time you upload code, $LATEST changes. Calling it is like running whatever is on the developer's desk.
  • A version (1, 2, 3 …) — a frozen snapshot of the code and the configuration (runtime, memory, environment variables, layers) taken when you publish. You can never edit a version; you can only publish a new one or delete an old one.
  • An alias (live, staging) — a named pointer to a version. An alias can also point to two versions at once with a weight, for example 90% to version 6 and 10% to version 7.

Callers — API Gateway, an SQS event source mapping, another service — should invoke the alias. A release then becomes three moves: publish a new version, gradually shift the alias towards it, and keep the old version around in case you need to point back.

AWS CodeDeploy automates the "gradually shift" part. You tell it "move live from version 6 to version 7 using 10% for 5 minutes, then the rest", and give it one or more CloudWatch alarms. If an alarm goes into ALARM during the shift, CodeDeploy points the alias back at version 6. Before shifting any traffic it can call a pre-traffic hook (a Lambda function you write that tests version 7 directly), and after shifting all traffic it can call a post-traffic hook.

Analogy: think of the alias as the sign over a bank branch's counter that says "Payments — window 6". A version is a cashier at a numbered window. Publishing a new version opens window 7 with a new cashier. A canary deployment sends one customer in ten to window 7 while a supervisor (the alarm) watches. If window 7 starts making mistakes, the supervisor turns the sign back to window 6. Window 6 never closed, so nobody waits.

What problem the AWS service solves

FeatureWhat it gives youHonest limits
VersionsImmutable, numbered snapshots of code + configurationVersion numbers only go up; you cannot reuse or edit one. Each version's package counts towards the Region's code storage quota (75 GB by default), so old versions must be cleaned up
AliasesA stable ARN (…:function:name:live) that callers use; can be repointed instantlyAn alias cannot point to $LATEST when it is weighted. Maximum two versions per alias
Weighted alias routingSend a fraction of invocations to a second versionBoth versions must have the same execution role and the same dead-letter-queue configuration (or none). Distribution is probabilistic, so at low traffic the real split can differ a lot from the configured split
CodeDeploy (Lambda compute platform)Automates canary, linear or all-at-once shifting; runs hooks; rolls back on alarms or hook failureNeeds a previous version to shift from, so the very first deployment is all-at-once. Hooks must report back within one hour or the deployment fails. No extra charge for CodeDeploy itself when deploying to Lambda
AWS SAM DeploymentPreferenceCreates the CodeDeploy application, deployment group and service role for you from a few lines of YAMLOpinionated naming; the default CodeDeploy role only lets CodeDeploy invoke hook functions whose names start with CodeDeployHook_

The predefined CodeDeploy configurations for Lambda are:

ConfigurationBehaviour
CodeDeployDefault.LambdaCanary10Percent5Minutes10% immediately, the remaining 90% after 5 minutes
CodeDeployDefault.LambdaCanary10Percent10Minutes10%, then the rest after 10 minutes
CodeDeployDefault.LambdaCanary10Percent15Minutes10%, then the rest after 15 minutes
CodeDeployDefault.LambdaCanary10Percent30Minutes10%, then the rest after 30 minutes
CodeDeployDefault.LambdaLinear10PercentEvery1Minute+10% every minute (about 10 minutes in total)
CodeDeployDefault.LambdaLinear10PercentEvery2Minutes+10% every 2 minutes
CodeDeployDefault.LambdaLinear10PercentEvery3Minutes+10% every 3 minutes
CodeDeployDefault.LambdaLinear10PercentEvery10Minutes+10% every 10 minutes
CodeDeployDefault.LambdaAllAtOnceEverything at once (hooks and alarms still apply)

You can also create your own canary or linear configuration (for example 5% for 30 minutes) with aws deploy create-deployment-config. In SAM, the same options are written without the CodeDeployDefault.Lambda prefix, for example Canary10Percent5Minutes.

Microsoft / Azure comparison

You know (Microsoft/Azure)AWS equivalentWhat's different
Azure Functions deployment slots (staging slot, swap)Lambda versions + aliasA slot is a whole running copy you swap; a Lambda version is an immutable snapshot and the alias just changes which snapshot receives invocations
Slot traffic routing percentage ("Testing in production")Weighted alias (AdditionalVersionWeights)Same idea; Lambda allows exactly two versions per alias
Auto-swap with warm-upCodeDeploy pre-traffic hookThe hook is your own Lambda function that must call PutLifecycleEventHookExecutionStatus; nothing happens automatically
Azure Monitor alert + manual swap backCodeDeploy automatic rollback on CloudWatch alarmRollback is part of the deployment, not a separate runbook
Azure DevOps release gates (query Azure Monitor)CodeDeploy alarms + hooks, or CodePipeline actionsGates are evaluated during traffic shifting, not just before
Function app "Always ready" instancesProvisioned concurrency on an aliasConfigured per alias or version, billed per GB-second while configured

Architecture

The order of events in one deployment is: Start → BeforeAllowTraffic (pre-traffic hook) → AllowTraffic (the shifting itself, watched by alarms) → AfterAllowTraffic (post-traffic hook) → End. Only the two hook stages run your code.

Security-boundary view

Four different roles, four different jobs. The pipeline never holds permission to invoke the payment validator directly; only the hook does, and only for the duration of the deployment.

Step-by-step implementation

Make every caller use the alias

Before any canary can work, every integration must invoke hl-m09-payment-validator:live, not the unqualified function name. Check API Gateway integrations, event source mappings, Step Functions tasks and any other service calling the function. If one caller uses the bare name, it invokes $LATEST and bypasses your carefully staged rollout.

Resource-based permissions must be granted on the alias, too: lambda add-permission --qualifier live. A permission on the unqualified function does not cover alias invocations from API Gateway.

Publish versions as part of the build, never by hand

A version should be created by the pipeline from a specific commit. AWS SAM does this with AutoPublishAlias; CDK does it with fn.CurrentVersion; Terraform does it with publish = true on aws_lambda_function. Write the Git commit SHA into the version description so that aws lambda list-versions-by-function becomes a release history.

Create the alarms that decide rollback

At minimum, alarm on the Errors metric for the alias, and on Errors for the new version (dimension ExecutedVersion). The second alarm catches problems that are diluted at 10% traffic: if version 7 fails every call but only gets one call in ten, the alias-level error rate may still look tolerable. Add a business alarm too — for payment validation, a sudden rise in "rejected" decisions is as bad as an exception.

Write the hooks

A pre-traffic hook invokes the new version directly (by version number, not through the alias) with synthetic, clearly fictional test data, checks the answer, and reports Succeeded or Failed to CodeDeploy. A post-traffic hook runs after 100% of traffic has shifted and does a broader smoke test. Both must always report a status, even when they crash; otherwise the deployment waits for the one-hour timeout.

Configure the deployment group

Choose a deployment configuration (start with LambdaCanary10Percent5Minutes for a payments function), attach the alarms, attach the hooks and turn on automatic rollback for failures and alarms.

Rehearse a failure

Deploy a version that throws on purpose (for example, behind an environment variable FAIL_VALIDATION=true in the test account). Watch CodeDeploy roll back. Record the time from alarm to rollback; that number belongs in your change template.

Clean up old versions on a schedule

Keep the last few versions for fast rollback and delete older ones so you do not hit the code storage quota. Never delete a version an alias still points to; Lambda will refuse anyway.

AWS Console instructions

Look at versions and aliases:

  1. Console → Lambda → Functions → hl-m09-payment-validator.
  2. The Versions tab lists every published version with its description. The Aliases tab lists each alias and the version(s) it points to.
  3. To create a weighted alias by hand: Aliases → Create alias, choose the main version, expand Weighted alias, choose the Additional version and enter the Weight (%). The main version receives the remainder automatically.

Watch a CodeDeploy deployment:

  1. Console → CodeDeploy → Deployments. Open the most recent deployment.
  2. The Deployment details panel shows the deployment configuration, the traffic-shifting progress and the lifecycle events (BeforeAllowTraffic, AllowTraffic, AfterAllowTraffic) with their status.
  3. If a rollback happened, the deployment shows as Stopped or Failed and a new rollback deployment appears with a reference to the original.

See which version handled a request:

  1. Console → CloudWatch → Log groups → /aws/lambda/hl-m09-payment-validator. Each START line contains Version: 7 (or 6).
  2. Console → CloudWatch → Metrics → Lambda → By Function Name, Resource, Executed Version to chart errors per version.

AWS CLI

# Variables used below. The function and alias names follow CONVENTIONS.md.
FN=hl-m09-payment-validator
P=learn-sandbox

# 1. Publish the current $LATEST code as an immutable version and record the commit.
#    --query returns just the new version number, e.g. "7".
NEW=$(aws lambda publish-version --function-name $FN \
  --description "git:$(git rev-parse --short HEAD)" \
  --query Version --output text --profile $P)

# 2. Read which version the alias points to today (the "current" version).
OLD=$(aws lambda get-alias --function-name $FN --name live \
  --query FunctionVersion --output text --profile $P)

# 3. Manual canary: keep 90% on OLD, send 10% to NEW.
#    The JSON form avoids shell quoting problems with the shorthand syntax.
aws lambda update-alias --function-name $FN --name live \
  --function-version "$OLD" \
  --routing-config "{\"AdditionalVersionWeights\":{\"$NEW\":0.1}}" \
  --profile $P

# 4. Look at the errors for the new version over the last 10 minutes.
aws cloudwatch get-metric-statistics --namespace AWS/Lambda --metric-name Errors \
  --dimensions Name=FunctionName,Value=$FN Name=Resource,Value=$FN:live Name=ExecutedVersion,Value=$NEW \
  --start-time "$(date -u -d '-10 min' +%Y-%m-%dT%H:%M:%SZ)" \
  --end-time "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --period 60 --statistics Sum --profile $P

# 5a. Promote: point the alias fully at NEW and clear the routing config.
aws lambda update-alias --function-name $FN --name live \
  --function-version "$NEW" --routing-config '{"AdditionalVersionWeights":{}}' --profile $P

# 5b. ...or roll back: point fully at OLD and clear the routing config.
aws lambda update-alias --function-name $FN --name live \
  --function-version "$OLD" --routing-config '{"AdditionalVersionWeights":{}}' --profile $P

# 6. Let CodeDeploy do the same thing with alarms and hooks instead.
#    The AppSpec says: move alias "live" from OLD to NEW and run the hooks.
cat > appspec.json <<EOF
{
  "version": 0.0,
  "Resources": [
    { "PaymentValidator": {
        "Type": "AWS::Lambda::Function",
        "Properties": { "Name": "$FN", "Alias": "live",
                        "CurrentVersion": "$OLD", "TargetVersion": "$NEW" } } }
  ],
  "Hooks": [
    { "BeforeAllowTraffic": "CodeDeployHook_hl-m09-pretraffic" },
    { "AfterAllowTraffic":  "CodeDeployHook_hl-m09-posttraffic" }
  ]
}
EOF

# The revision wraps the AppSpec as a string (jq -Rs turns the file into one JSON string).
jq -n --arg c "$(cat appspec.json)" \
  '{revisionType:"AppSpecContent", appSpecContent:{content:$c}}' > revision.json

DEP=$(aws deploy create-deployment \
  --application-name hl-m09-payments \
  --deployment-group-name hl-m09-payment-validator-dg \
  --revision file://revision.json \
  --query deploymentId --output text --profile $P)

# 7. Wait for the result and print the final status (Succeeded, Failed or Stopped).
aws deploy wait deployment-successful --deployment-id "$DEP" --profile $P || true
aws deploy get-deployment --deployment-id "$DEP" \
  --query 'deploymentInfo.[status,rollbackInfo.rollbackMessage]' --output text --profile $P

# 8. List versions with their descriptions (your release history).
aws lambda list-versions-by-function --function-name $FN \
  --query 'Versions[].[Version,Description,LastModified]' --output table --profile $P

The weight is a fraction between 0 and 1, not a percentage. 0.1 means 10%.

Infrastructure as Code

template.yaml
AWSTemplateFormatVersion: "2010-09-09"
Transform: AWS::Serverless-2016-10-31
Description: Harbourline payment validator with canary deployment (lab m09)

Globals:
  Function:
    Runtime: dotnet10
    Architectures: [arm64]
    MemorySize: 1024
    Timeout: 10
    Tags:
      Project: cea-lab
      Lab: m09-l8
      Environment: learn
      Owner: your-name

Resources:
  PaymentValidatorFunction:
    Type: AWS::Serverless::Function
    Properties:
      FunctionName: hl-m09-payment-validator
      CodeUri: src/Harbourline.Payments.Validator/
      Handler: Harbourline.Payments.Validator::Harbourline.Payments.Validator.Function::Handler
      AutoPublishAlias: live            # publish a version on every code change and move "live"
      DeploymentPreference:
        Type: Canary10Percent5Minutes   # 10% for 5 minutes, then 100%
        Alarms:
          - !Ref AliasErrorsAlarm
          - !Ref NewVersionErrorsAlarm
        Hooks:
          PreTraffic: !Ref PreTrafficHookFunction
          PostTraffic: !Ref PostTrafficHookFunction

  PreTrafficHookFunction:
    Type: AWS::Serverless::Function
    Properties:
      # The SAM-created CodeDeploy role may only invoke functions named CodeDeployHook_*
      FunctionName: CodeDeployHook_hl-m09-pretraffic
      CodeUri: src/Harbourline.Payments.DeployHooks/
      Handler: Harbourline.Payments.DeployHooks::Harbourline.Payments.DeployHooks.PreTrafficHook::Handler
      Timeout: 120
      DeploymentPreference:
        Enabled: false                  # never canary the hook itself
      Environment:
        Variables:
          # SAM resolves this to the ARN of the version being deployed
          TARGET_FUNCTION_ARN: !Ref PaymentValidatorFunction.Version
      Policies:
        - Version: "2012-10-17"
          Statement:
            - Effect: Allow
              Action: codedeploy:PutLifecycleEventHookExecutionStatus
              Resource: !Sub arn:${AWS::Partition}:codedeploy:${AWS::Region}:${AWS::AccountId}:deploymentgroup:${ServerlessDeploymentApplication}/*
            - Effect: Allow
              Action: lambda:InvokeFunction
              Resource: !Sub arn:${AWS::Partition}:lambda:${AWS::Region}:${AWS::AccountId}:function:hl-m09-payment-validator:*

  PostTrafficHookFunction:
    Type: AWS::Serverless::Function
    Properties:
      FunctionName: CodeDeployHook_hl-m09-posttraffic
      CodeUri: src/Harbourline.Payments.DeployHooks/
      Handler: Harbourline.Payments.DeployHooks::Harbourline.Payments.DeployHooks.PostTrafficHook::Handler
      Timeout: 120
      DeploymentPreference:
        Enabled: false
      Environment:
        Variables:
          TARGET_FUNCTION_ARN: !Sub arn:${AWS::Partition}:lambda:${AWS::Region}:${AWS::AccountId}:function:hl-m09-payment-validator:live
      Policies:
        - Version: "2012-10-17"
          Statement:
            - Effect: Allow
              Action: codedeploy:PutLifecycleEventHookExecutionStatus
              Resource: !Sub arn:${AWS::Partition}:codedeploy:${AWS::Region}:${AWS::AccountId}:deploymentgroup:${ServerlessDeploymentApplication}/*
            - Effect: Allow
              Action: lambda:InvokeFunction
              Resource: !Sub arn:${AWS::Partition}:lambda:${AWS::Region}:${AWS::AccountId}:function:hl-m09-payment-validator:live

  AliasErrorsAlarm:
    Type: AWS::CloudWatch::Alarm
    Properties:
      AlarmName: hl-m09-payment-validator-live-errors
      Namespace: AWS/Lambda
      MetricName: Errors
      Dimensions:
        - { Name: FunctionName, Value: hl-m09-payment-validator }
        - { Name: Resource, Value: hl-m09-payment-validator:live }
      Statistic: Sum
      Period: 60
      EvaluationPeriods: 1
      Threshold: 1
      ComparisonOperator: GreaterThanOrEqualToThreshold
      TreatMissingData: notBreaching

  NewVersionErrorsAlarm:
    Type: AWS::CloudWatch::Alarm
    Properties:
      AlarmName: hl-m09-payment-validator-newversion-errors
      Namespace: AWS/Lambda
      MetricName: Errors
      Dimensions:
        - { Name: FunctionName, Value: hl-m09-payment-validator }
        - { Name: Resource, Value: hl-m09-payment-validator:live }
        # ⚠ VERIFY: SAM attribute syntax for the published version number
        - { Name: ExecutedVersion, Value: !GetAtt PaymentValidatorFunction.Version.Version }
      Statistic: Sum
      Period: 60
      EvaluationPeriods: 1
      Threshold: 1
      ComparisonOperator: GreaterThanOrEqualToThreshold
      TreatMissingData: notBreaching

ServerlessDeploymentApplication is the logical ID SAM gives the CodeDeploy application it creates. If your SAM version names it differently, check the transformed template with sam validate --debug or in the CloudFormation console's Template → View processed template ⚠ VERIFY for your SAM CLI version.

Complete code

The hooks below are real, runnable .NET 10 Lambda handlers. They live in a class library Harbourline.Payments.DeployHooks next to the validator. They use dependency injection through constructors so you can unit-test them with fakes and no AWS account.

src/Harbourline.Payments.DeployHooks/Harbourline.Payments.DeployHooks.csproj
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <GenerateRuntimeConfigurationFiles>true</GenerateRuntimeConfigurationFiles>
    <AWSProjectType>Lambda</AWSProjectType>
    <RootNamespace>Harbourline.Payments.DeployHooks</RootNamespace>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Amazon.Lambda.Core" Version="3.4.0" />
    <PackageReference Include="Amazon.Lambda.Serialization.SystemTextJson" Version="3.0.1" />
    <PackageReference Include="AWSSDK.CodeDeploy" Version="4.1.0.2" />
    <PackageReference Include="AWSSDK.Lambda" Version="4.1.3" />
  </ItemGroup>
</Project>
src/Harbourline.Payments.DeployHooks/HookBase.cs
using System.Text;
using System.Text.Json;
using Amazon.CodeDeploy;
using Amazon.CodeDeploy.Model;
using Amazon.Lambda;
using Amazon.Lambda.Core;
using Amazon.Lambda.Model;

[assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))]

namespace Harbourline.Payments.DeployHooks;

/// <summary>The payload CodeDeploy sends to every Lambda lifecycle hook.</summary>
public sealed record CodeDeployHookEvent(string DeploymentId, string LifecycleEventHookExecutionId);

/// <summary>One synthetic check: a request to send and a rule for the expected answer.</summary>
public sealed record SmokeCase(string Name, object Request, Func<JsonElement, bool> IsExpected);

public abstract class HookBase
{
    private readonly IAmazonCodeDeploy _codeDeploy;
    private readonly IAmazonLambda _lambda;
    private readonly string _targetFunctionArn;

    protected HookBase(IAmazonCodeDeploy codeDeploy, IAmazonLambda lambda, string targetFunctionArn)
    {
        _codeDeploy = codeDeploy;
        _lambda = lambda;
        _targetFunctionArn = targetFunctionArn;
    }

    /// <summary>The checks this hook runs. Pre- and post-traffic hooks supply different lists.</summary>
    protected abstract IReadOnlyList<SmokeCase> Cases { get; }

    public async Task Handler(CodeDeployHookEvent evt, ILambdaContext context)
    {
        var status = LifecycleEventStatus.Failed;   // fail closed: assume failure until proven otherwise
        try
        {
            var failures = new List<string>();
            foreach (var smoke in Cases)
            {
                var (ok, detail) = await RunCaseAsync(smoke);
                context.Logger.LogInformation(JsonSerializer.Serialize(new
                {
                    evt.DeploymentId, check = smoke.Name, ok, detail, target = _targetFunctionArn
                }));
                if (!ok) failures.Add(smoke.Name);
            }
            if (failures.Count == 0) status = LifecycleEventStatus.Succeeded;
        }
        catch (Exception ex)
        {
            // Never let an exception escape without reporting: CodeDeploy would wait up to an hour.
            context.Logger.LogError($"Hook crashed for deployment {evt.DeploymentId}: {ex.GetType().Name}");
        }
        finally
        {
            await _codeDeploy.PutLifecycleEventHookExecutionStatusAsync(
                new PutLifecycleEventHookExecutionStatusRequest
                {
                    DeploymentId = evt.DeploymentId,
                    LifecycleEventHookExecutionId = evt.LifecycleEventHookExecutionId,
                    Status = status
                });
        }
    }

    private async Task<(bool Ok, string Detail)> RunCaseAsync(SmokeCase smoke)
    {
        var response = await _lambda.InvokeAsync(new InvokeRequest
        {
            FunctionName = _targetFunctionArn,                  // a qualified ARN: version or alias
            InvocationType = InvocationType.RequestResponse,
            Payload = JsonSerializer.Serialize(smoke.Request)
        });

        if (!string.IsNullOrEmpty(response.FunctionError))
            return (false, $"function error: {response.FunctionError}");

        var body = Encoding.UTF8.GetString(response.Payload.ToArray());
        using var doc = JsonDocument.Parse(body);
        return smoke.IsExpected(doc.RootElement)
            ? (true, "expected result")
            : (false, "unexpected result");
    }

    protected static string RequiredEnv(string name) =>
        System.Environment.GetEnvironmentVariable(name)
        ?? throw new System.InvalidOperationException($"Environment variable {name} is not set.");
}
src/Harbourline.Payments.DeployHooks/PreTrafficHook.cs
using System.Text.Json;
using Amazon.CodeDeploy;
using Amazon.Lambda;

namespace Harbourline.Payments.DeployHooks;

/// <summary>
/// Runs BEFORE any customer traffic reaches the new version. It invokes the new
/// version directly (TARGET_FUNCTION_ARN is the version ARN) with fictional payments.
/// </summary>
public sealed class PreTrafficHook : HookBase
{
    // Parameterless constructor used by the Lambda runtime.
    public PreTrafficHook()
        : this(new AmazonCodeDeployClient(), new AmazonLambdaClient(), RequiredEnv("TARGET_FUNCTION_ARN")) { }

    // Constructor used by unit tests.
    public PreTrafficHook(IAmazonCodeDeploy codeDeploy, IAmazonLambda lambda, string targetFunctionArn)
        : base(codeDeploy, lambda, targetFunctionArn) { }

    protected override IReadOnlyList<SmokeCase> Cases { get; } =
    [
        new("valid FPS payment is accepted",
            new
            {
                paymentId = "PAY-0193b3c0-0000-7000-8000-000000000001",
                debtorAccountId = "ACC-0000000001",
                creditorName = "Test Creditor Ltd",
                creditorIban = "GB33BUKB20201555555555",   // published example IBAN, fictional
                amount = 25.00m,
                currency = "GBP",
                scheme = "FPS"
            },
            r => r.GetProperty("decision").GetString() == "accepted"),

        new("bad IBAN checksum is rejected",
            new
            {
                paymentId = "PAY-0193b3c0-0000-7000-8000-000000000002",
                debtorAccountId = "ACC-0000000001",
                creditorName = "Test Creditor Ltd",
                creditorIban = "GB00BUKB20201555555555",   // checksum deliberately wrong
                amount = 25.00m,
                currency = "GBP",
                scheme = "FPS"
            },
            r => r.GetProperty("decision").GetString() == "rejected"
                 && r.GetProperty("reason").GetString() == "invalid_iban")
    ];
}
src/Harbourline.Payments.DeployHooks/PostTrafficHook.cs
using Amazon.CodeDeploy;
using Amazon.Lambda;

namespace Harbourline.Payments.DeployHooks;

/// <summary>
/// Runs AFTER 100% of traffic is on the new version. Invokes the alias, so it tests
/// exactly what customers now reach. Keep it short: rollback is still possible here.
/// </summary>
public sealed class PostTrafficHook : HookBase
{
    public PostTrafficHook()
        : this(new AmazonCodeDeployClient(), new AmazonLambdaClient(), RequiredEnv("TARGET_FUNCTION_ARN")) { }

    public PostTrafficHook(IAmazonCodeDeploy codeDeploy, IAmazonLambda lambda, string targetFunctionArn)
        : base(codeDeploy, lambda, targetFunctionArn) { }

    protected override IReadOnlyList<SmokeCase> Cases { get; } =
    [
        new("SEPA instant payment in EUR is accepted",
            new
            {
                paymentId = "PAY-0193b3c0-0000-7000-8000-000000000003",
                debtorAccountId = "ACC-0000000002",
                creditorName = "Beispiel GmbH",
                creditorIban = "DE89370400440532013000",   // published example IBAN, fictional
                amount = 10.00m,
                currency = "EUR",
                scheme = "SEPA_INST"
            },
            r => r.GetProperty("decision").GetString() == "accepted")
    ];
}
tests/Harbourline.Payments.DeployHooks.Tests/PreTrafficHookTests.cs
using System.Text;
using Amazon.CodeDeploy;
using Amazon.CodeDeploy.Model;
using Amazon.Lambda;
using Amazon.Lambda.Model;
using Amazon.Lambda.TestUtilities;
using Harbourline.Payments.DeployHooks;
using NSubstitute;
using Xunit;

public class PreTrafficHookTests
{
    private const string Target = "arn:aws:lambda:us-east-1:111122223333:function:hl-m09-payment-validator:7";

    private static InvokeResponse Reply(string json) =>
        new() { StatusCode = 200, Payload = new MemoryStream(Encoding.UTF8.GetBytes(json)) };

    [Fact]
    public async Task Reports_failed_when_new_version_accepts_a_bad_iban()
    {
        var codeDeploy = Substitute.For<IAmazonCodeDeploy>();
        var lambda = Substitute.For<IAmazonLambda>();
        // The (buggy) new version accepts everything.
        lambda.InvokeAsync(Arg.Any<InvokeRequest>(), Arg.Any<CancellationToken>())
              .Returns(_ => Reply("""{"decision":"accepted"}"""));

        var hook = new PreTrafficHook(codeDeploy, lambda, Target);
        await hook.Handler(new CodeDeployHookEvent("d-TEST123", "hook-1"), new TestLambdaContext());

        await codeDeploy.Received(1).PutLifecycleEventHookExecutionStatusAsync(
            Arg.Is<PutLifecycleEventHookExecutionStatusRequest>(r =>
                r.Status == LifecycleEventStatus.Failed && r.DeploymentId == "d-TEST123"),
            Arg.Any<CancellationToken>());
    }

    [Fact]
    public async Task Reports_failed_even_when_invoke_throws()
    {
        var codeDeploy = Substitute.For<IAmazonCodeDeploy>();
        var lambda = Substitute.For<IAmazonLambda>();
        lambda.InvokeAsync(Arg.Any<InvokeRequest>(), Arg.Any<CancellationToken>())
              .Returns<InvokeResponse>(_ => throw new AmazonLambdaException("throttled"));

        var hook = new PreTrafficHook(codeDeploy, lambda, Target);
        await hook.Handler(new CodeDeployHookEvent("d-TEST124", "hook-2"), new TestLambdaContext());

        await codeDeploy.Received(1).PutLifecycleEventHookExecutionStatusAsync(
            Arg.Is<PutLifecycleEventHookExecutionStatusRequest>(r => r.Status == LifecycleEventStatus.Failed),
            Arg.Any<CancellationToken>());
    }
}

The test project references xunit.v3 4.0.3, NSubstitute and Amazon.Lambda.TestUtilities 4.3.0, with <OutputType>Exe</OutputType> as described in CONVENTIONS.md. The full runnable version of this pattern is part of Lab 9.5 (see the module project).

Finally, the GitHub Actions job that deploys the SAM application. It assumes the OIDC role from earlier in the module; there are no stored AWS keys.

.github/workflows/deploy-payment-validator.yml
name: deploy-payment-validator
on:
  push:
    branches: [main]
    paths: ["services/payment-validator/**"]

permissions:
  contents: read
  id-token: write        # needed to request the OIDC token

jobs:
  deploy-test:
    runs-on: ubuntu-24.04
    environment: test    # the OIDC "sub" claim includes environment:test
    defaults:
      run:
        working-directory: services/payment-validator
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - uses: actions/setup-dotnet@0f4a354dd5547a28c70b7853dbd95d5b67886e73 # v6.1.0
        with:
          dotnet-version: "10.0.x"
      - uses: aws-actions/setup-sam@341eee193f458fa5aae5d52c94b0c5cf3a1c5a52 # v3
        with:
          use-installer: true
      - uses: aws-actions/configure-aws-credentials@e1253824e5c10ff9df46874f81ed3ec929e19cfd # v6.3.0
        with:
          role-to-assume: ${{ vars.DEPLOY_ROLE_ARN }}
          aws-region: us-east-1
      - name: Unit tests
        run: dotnet test --solution PaymentValidator.slnx
      - name: Build
        run: sam build
      - name: Deploy (CodeDeploy performs the canary)
        run: >
          sam deploy --stack-name hl-m09-payment-validator
          --capabilities CAPABILITY_IAM
          --resolve-s3
          --no-confirm-changeset --no-fail-on-empty-changeset
          --tags Project=cea-lab Lab=m09-l8 Environment=learn

sam deploy returns only when CloudFormation finishes, and CloudFormation waits for the CodeDeploy deployment to complete or roll back. A failed canary therefore fails the GitHub job — exactly the behaviour you want in the audit trail.

Code explained line by line

HookBase.cs

  1. [assembly: LambdaSerializer(...)] — tells the Lambda runtime to use System.Text.Json to turn the incoming JSON into CodeDeployHookEvent.
  2. record CodeDeployHookEvent(string DeploymentId, string LifecycleEventHookExecutionId) — CodeDeploy sends exactly these two values. You must echo both back.
  3. record SmokeCase(...) — one synthetic check: a name for the logs, the request object, and a predicate that decides whether the answer is right. Keeping checks as data makes it easy to add a new case per bug fix.
  4. Constructor taking IAmazonCodeDeploy and IAmazonLambda — interfaces from the SDK v4, so tests can pass substitutes.
  5. var status = LifecycleEventStatus.Failed; — fail closed. If anything goes wrong before the end, the deployment rolls back.
  6. The foreach runs every case and logs one structured JSON line per check, including the deployment ID, so an auditor can trace which checks ran for which release.
  7. catch (Exception ex) — logs only the exception type, not the message, so a payload echoed in an exception message does not leak into logs.
  8. finally { PutLifecycleEventHookExecutionStatusAsync(...) } — reports the result no matter what. Without this, a crash leaves the deployment hanging until the one-hour timeout.
  9. InvokeAsync with FunctionName = _targetFunctionArn — a qualified ARN (ending :7 or :live). Invoking the unqualified name would test $LATEST, which may not be what you are deploying.
  10. response.FunctionError — Lambda reports an unhandled exception in the function by setting this field with HTTP 200; checking only the status code would miss it.
  11. JsonDocument.Parse(body) then smoke.IsExpected(...) — the business assertion, e.g. "a bad IBAN must be rejected with reason invalid_iban".
  12. RequiredEnv — fails fast with a clear message if the template forgot to pass the target ARN.

PreTrafficHook.cs / PostTrafficHook.cs

  1. The parameterless constructor is what the Lambda runtime calls; it builds real SDK clients that pick up the function's execution role credentials automatically.
  2. The second constructor is for tests.
  3. The pre-traffic hook targets the version ARN (SAM's PaymentValidatorFunction.Version), so it tests the new code before any customer can reach it. The post-traffic hook targets the alias, so it tests exactly what customers now use.
  4. The IBANs are well-known published example values with valid checksums and the deliberately broken GB00… variant; no real customer data is involved. Payment IDs follow the PAY- + UUID v7 shape from CONVENTIONS.md.

SAM template

  1. AutoPublishAlias: live — on every code change, SAM publishes a version and creates or updates the live alias.
  2. DeploymentPreference.Type: Canary10Percent5Minutes — SAM creates a CodeDeploy application and deployment group with that configuration.
  3. Alarms — any alarm in ALARM during the deployment triggers rollback.
  4. Hooks.PreTraffic / PostTraffic — the hook functions. Their names start with CodeDeployHook_ because the default CodeDeploy service role SAM creates may only invoke such functions.
  5. DeploymentPreference: Enabled: false on the hooks — the hooks themselves are deployed all at once; a canary of the tester makes no sense.
  6. TARGET_FUNCTION_ARN: !Ref PaymentValidatorFunction.Version — SAM exposes the version it publishes as <LogicalId>.Version; !Ref gives its ARN.
  7. Hook Policies — only two permissions: report status to this application's deployment groups, and invoke versions of the one validator function.
  8. The two alarms use the Resource dimension (function:alias) and, for the second, the ExecutedVersion dimension, so the new version's errors are visible even at 10% traffic.

Security considerations

⚠ Learning shortcut — not for production

In this lesson the pipeline's deploy role in the sandbox account is allowed to run sam deploy with CAPABILITY_IAM, which means CloudFormation can create IAM roles. In production, give the deploy role permission to pass only a CloudFormation execution role that is restricted by a permissions boundary, and require that any new IAM role in the stack carries that boundary. See Permission boundaries, SCPs and RCPs.

⚠ Learning shortcut — not for production

The hooks call the function under test with synthetic payments. In production, make sure the validator treats these as test traffic: use a dedicated test debtor account (ACC-0000000001) that downstream services recognise and never settle, and mark the request with a header or field your logs and metrics can filter. Otherwise synthetic payments pollute fraud models and management information.

  • Execution role is shared across versions. Weighted routing requires both versions to use the same execution role, so you cannot "try out" a new, narrower role with a canary. Change the role in a separate, all-at-once release with its own testing.
  • Environment variables are part of the version. A secret placed in an environment variable is frozen into every version that ever had it. Load secrets at runtime from Secrets Manager or Parameter Store instead (see Secrets in CI/CD).
  • Resource policies on the alias. Grant lambda:InvokeFunction to API Gateway or another account on the alias (--qualifier live), not on the whole function, so that a caller cannot reach an older or newer version by number.
  • Who may move the alias? lambda:UpdateAlias on the live alias is effectively "release to production". Restrict it to the CodeDeploy service role and the break-glass role, and alert on any other principal using it (CloudTrail + EventBridge).
  • Logs. Each hook writes one structured line per check, including the deployment ID. Set a log retention period on the hook log groups (for example 400 days if that matches your bank's change-record retention), not "never expire".

Banking use case

Harbourline's Payments team runs three Lambda functions on the critical path: payment-validator, cutoff-calculator and sanctions-hook. Their release policy, agreed with the change-advisory board, reads:

FunctionDeployment configurationAlarmsHooks
payment-validatorLambdaCanary10Percent10MinutesErrors on alias and new version; "rejected decisions > 3x 7-day baseline"Pre: 12 synthetic payments across FPS, BACS, CHAPS, SEPA_CT, SEPA_INST. Post: 3 payments
cutoff-calculatorLambdaLinear10PercentEvery2MinutesErrors; p99 duration > 800 msPre: cut-off table checks at 14:59 and 15:01 UTC
sanctions-hookLambdaAllAtOnce during the Saturday window, hooks onlyErrors; throttlesPre: known test names must match the sanctions test list

The CAB treats a deployment with these settings as a standard change: pre-approved, no meeting needed, because the risk controls are automatic and evidenced. Anything else — for example a change of execution role or a new environment variable that points at a different downstream system — is a normal change that needs explicit approval. This is exactly the split described in Release management and audit evidence.

Common mistakes

  • Callers use the unqualified function name → they invoke $LATEST, so the canary protects nobody → check every integration and event source mapping for :live.
  • Alarm only on the alias → a version that fails every request at 10% traffic may not breach a threshold designed for 100% → add an ExecutedVersion alarm or a percentage-based metric-math alarm.
  • Hook crashes without reporting → deployment sits in BeforeAllowTraffic for an hour → report in finally, fail closed.
  • Hook invokes the alias in pre-traffic → it tests the old version, because no traffic has shifted yet → use the version ARN for pre-traffic.
  • Canarying a function with almost no traffic → at three invocations per hour, a 10%/5-minute canary sees zero requests on the new version and "passes" → rely on hooks for low-traffic functions, or use a longer canary with synthetic traffic.
  • Changing the execution role and the code together → weighted routing is not allowed with different roles, so the deployment fails or is forced all-at-once → split the changes.
  • Never deleting old versions → code storage quota reached after months of releases → schedule a clean-up that keeps the last N versions.

Troubleshooting

SymptomLikely causeFix
Deployment stuck at BeforeAllowTraffic for up to an hour, then failsHook did not call PutLifecycleEventHookExecutionStatus (crashed, timed out or lacks permission)Check the hook's CloudWatch logs; add the finally block; grant codedeploy:PutLifecycleEventHookExecutionStatus
AccessDenied invoking hook, deployment fails immediatelyCodeDeploy role cannot invoke a function whose name does not start with CodeDeployHook_Rename the hook or grant the CodeDeploy role invoke permission on it
update-alias returns an error about routing configSecond version uses a different execution role or DLQ, or you tried to route to $LATESTPublish both versions with the same role and DLQ settings
First SAM deployment ignores DeploymentPreferenceThere is no previous version to shift fromExpected. Deploy once, then canaries work from the second deployment
Canary shows 30% traffic on new version at 10% weightProbabilistic routing at low volumeNormal at low traffic; judge with per-version metrics, not by eye
Rollback happened but nobody knows whyAlarm in ALARM state from an unrelated earlier incidentCheck alarm history; ensure alarms are OK before deploying, and make the pipeline check that
CodeStorageExceededException on publishToo many old versionsDelete unused versions not referenced by any alias
Provisioned concurrency spillover during canaryProvisioned concurrency only on the old versionConfigure provisioned concurrency on the alias, sized for the weighted split

Cost and cleanup

Cost: Lambda invocations and the hook runs fit within the always-free Lambda allowance (1M requests and 400,000 GB-seconds per month). CodeDeploy has no extra charge for Lambda deployments. Two CloudWatch standard alarms fall inside the free allowance of 10 alarms per month; beyond that, a standard-resolution alarm costs about $0.10 per month ⚠ VERIFY current CloudWatch pricing. Label: free. Provisioned concurrency is not free: if you try it, remove it the same day.

# Delete the SAM stack (removes functions, versions, alias, CodeDeploy app and group, alarms).
sam delete --stack-name hl-m09-payment-validator --no-prompts --profile learn-sandbox

# If you created things with the CLI instead, remove them explicitly:
aws deploy delete-deployment-group --application-name hl-m09-payments \
  --deployment-group-name hl-m09-payment-validator-dg --profile learn-sandbox
aws deploy delete-application --application-name hl-m09-payments --profile learn-sandbox
aws lambda delete-function --function-name hl-m09-payment-validator --profile learn-sandbox

# Log groups are not deleted with the function. Remove them too.
for g in /aws/lambda/hl-m09-payment-validator /aws/lambda/CodeDeployHook_hl-m09-pretraffic /aws/lambda/CodeDeployHook_hl-m09-posttraffic; do
  aws logs delete-log-group --log-group-name "$g" --profile learn-sandbox || true
done

# Confirm nothing tagged for this lab remains.
aws resourcegroupstaggingapi get-resources --tag-filters Key=Project,Values=cea-lab Key=Lab,Values=m09-l8 \
  --query 'ResourceTagMappingList[].ResourceARN' --profile learn-sandbox

Exercises

  • 🟢 Guided: Deploy the SAM template twice: first as is, then after changing the validator's response message. Open CodeDeploy → Deployments and watch the 10% step, then the 100% step. Note the version numbers before and after.
  • 🟡 Challenge: Add a custom deployment configuration "5% for 20 minutes" with aws deploy create-deployment-config and switch the deployment group to it. Add a metric-math alarm that fires when the new version's error rate (Errors / Invocations) exceeds 2%.
  • 🔴 Live problem: The on-call engineer reports: "Friday's release of cutoff-calculator passed its canary, but on Monday 08:00 BACS payments started failing. CodeDeploy says the deployment succeeded." Using only CloudWatch metrics, logs and the deployment history, work out why the canary did not catch it and propose two changes to the deployment process.

Assignment

In your portfolio repository, add a deploy/ folder for one Lambda function containing: the SAM or CDK definition with a canary deployment and two alarms; a pre-traffic hook in C# with at least three synthetic cases and unit tests that pass without AWS; and a one-page RELEASE.md that states the deployment configuration, the rollback trigger, the expected time to roll back and how you rehearsed it.

Solutions

Knowledge check

Interview questions

  • "How do you roll back a Lambda function in production?" — Callers use an alias; every release is a published version. Rollback is repointing the alias at the previous version, which CodeDeploy does automatically when an alarm fires or a hook fails. Manually it is one update-alias command. Database or contract changes need their own plan, because repointing code doesn't undo data.
  • "Canary or linear — which do you choose?" — Canary when you want a cheap early signal and then a fast finish (most APIs). Linear when risk grows with load, such as connection pools or downstream rate limits, so you see behaviour at 10, 20, 30%… Neither helps if there is no traffic, so hooks matter for quiet functions.
  • "What goes in a pre-traffic hook?" — Fast, deterministic checks of the new version using synthetic data that downstream systems recognise as test data: happy path, a known rejection, a config sanity check. It must report status in every code path and must not need production secrets it would not otherwise have.
  • "What's the relationship between SnapStart and versions?" — SnapStart (supported for .NET managed runtimes) takes its snapshot when you publish a version, so it only applies to published versions and aliases, never to $LATEST. Publishing therefore takes longer, and any uniqueness (random seeds, connections) must be re-established after restore.

Certification practice

Completion checklist

  • I can explain $LATEST, version and alias to a colleague in two sentences
  • Every caller of my function uses the alias ARN, and permissions are granted on the alias
  • I ran a canary with CodeDeploy and watched both traffic steps
  • I wrote a pre-traffic hook in C# that reports status in every code path, with unit tests
  • I rehearsed an alarm-driven rollback and recorded how long it took
  • I ran the cleanup and confirmed nothing tagged Lab=m09-l8 remains

Key takeaways

  • Versions are immutable snapshots; aliases are the names callers use; a release is "move the alias".
  • CodeDeploy turns alias moves into canary or linear shifts with alarms and hooks, and rolls back automatically.
  • Pre-traffic hooks test the version; post-traffic hooks test the alias. Both fail closed and always report.
  • A canary only tests the traffic that arrives during it: add per-version alarms and synthetic checks.
  • Code rollback is cheap; data and contract rollback is not — that is the next lesson.

Further reading

Independent learning resource — not affiliated with, endorsed or sponsored by Amazon Web Services. AWS and related marks are trademarks of Amazon.com, Inc. or its affiliates. All banking data in examples is fictional. Sample architectures are for learning and are not automatically compliant with GDPR, PCI DSS or any banking regulation.

On this page