Introduction

In CloudFormation, you create a published Lambda version with the AWS::Lambda::Version resource. The usual pattern is to define the function as AWS::Lambda::Function, then add a version resource that points at that function, and optionally point an alias at the published version.

The important detail is that Lambda versions are immutable. CloudFormation will only create a meaningful new version when the function code or relevant version-triggering configuration has changed, or when the version resource itself is forced to change.

Define the Function and the Version

A basic template looks like this:

1Resources:
2  MyFunction:
3    Type: AWS::Lambda::Function
4    Properties:
5      FunctionName: my-function
6      Runtime: python3.11
7      Handler: index.handler
8      Role: arn:aws:iam::123456789012:role/lambda-exec-role
9      Code:
10        S3Bucket: my-artifacts-bucket
11        S3Key: lambda/my-function.zip
12
13  MyFunctionVersion:
14    Type: AWS::Lambda::Version
15    Properties:
16      FunctionName: !Ref MyFunction
17      Description: Release 2025-09-23

When CloudFormation creates MyFunctionVersion, Lambda publishes an immutable version of the function state at that point.

Use an Alias for Stable Traffic Routing

Most real deployments also define an alias:

1  MyFunctionAlias:
2    Type: AWS::Lambda::Alias
3    Properties:
4      Name: live
5      FunctionName: !Ref MyFunction
6      FunctionVersion: !GetAtt MyFunctionVersion.Version

The alias gives clients a stable ARN such as live, while the published version number changes over time. This is much easier to operate than asking every downstream system to call version 17, then 18, then 19 directly.

Why a New Version Sometimes Does Not Appear

A common source of confusion is that updating the function resource does not always mean you get a new published version automatically. CloudFormation needs the version resource to resolve to a distinct publish action.

In practice, a new version is normally created when:

• the function code package changed
• version-relevant configuration changed
• the version resource is updated in a way that causes republishing

If you keep the exact same code and same effective version input, you should not expect a new meaningful immutable version to appear.

That is why deployment pipelines usually tie the code artifact key, hash, or version description to each release.

Make Version Creation Intentional

One helpful pattern is to include a release identifier in the version description or artifact location:

1Parameters:
2  ReleaseId:
3    Type: String
4
5Resources:
6  MyFunctionVersion:
7    Type: AWS::Lambda::Version
8    Properties:
9      FunctionName: !Ref MyFunction
10      Description: !Sub "Release ${ReleaseId}"

That makes the CloudFormation update intent clearer. It also helps humans understand which deployment a published version corresponds to. It is especially useful when a stack is updated frequently from CI and you need to correlate infrastructure changes with application releases.

Think in Terms of Function, Version, and Alias

The deployment model is easiest to reason about if you separate the three layers:

• function: mutable working definition
• version: immutable snapshot
• alias: stable pointer to a chosen version

Once you think this way, rollbacks and deployments become simpler. You publish a new version, then move the alias if the release is good.

Common Pitfalls

• Expecting AWS::Lambda::Function updates alone to behave like immutable version publishing.
• Forgetting that AWS::Lambda::Version creates immutable snapshots, so old versions do not change.
• Invoking raw version numbers directly when an alias would be easier to manage.
• Reusing the same artifact and metadata and then wondering why versioning behavior seems unchanged.

Summary

• Use AWS::Lambda::Version in CloudFormation to publish a Lambda version.
• Point an AWS::Lambda::Alias at that version for stable invocation.
• New versions are meaningful only when the function state or release inputs actually change.
• Treat function, version, and alias as three separate deployment concepts.
• Make release identity explicit so CloudFormation-driven versioning stays predictable.