how can I use lambda versions and aliases to version my API with CloudFormation?

Question

We have an API which needs to be versioned. We are using API Gateway and Lambda on AWS. All code is deployed using CICD, and we use SAM templates on top of CloudFormation.

NB we are using API Gateway stages to handle different environments (e.g. stage "dev1" points to lambda "dev1-MyService".

We have a resource 'v1' defined as follows:

  V1Resource:
    Type: AWS::ApiGateway::Resource
    Properties:
      RestApiId: !Ref Api
      ParentId: !GetAtt Api.RootResourceId
      PathPart: 'v1'

# proxy traffic to a lambda:

  ProxyMethod:
    Type: AWS::ApiGateway::Method
    Properties:
      HttpMethod: ANY
...
      Integration:
        Type: AWS_PROXY
        Uri: arn:aws:apigateway:...:function:MyFunction:v1/invocations'

And a lambda defined like this:

  ApiFunction:
    Type: AWS::Serverless::Function
    Properties:
      AutoPublishAlias: "v1"
      FunctionName: MyFunction
...

What we want to do is keep the v1 lambda in the system, but when we have breaking changes to the API, we can define a /v2/ resource, pointing to the v2 alias of the lambda

My plan was to define a second resource (V2Resource) and second proxy method, referencing the v2 alias of the lambda, which I could create by bumping AutoPublishAlias to v2 in the same change.

Then the v2 alias remains pointing to the old version (forever in theory) and each time we deploy from then on, the latest version of the API is aliased to v2 (until we need to do another breaking change and introduce v3).

Unfortunately, when I do that, it deletes the old alias v1.

So how am I supposed to use Lambda aliases to do API versioning with API Gateway? With CloudFormation and SAM templates?

Answer 1

You could use AWS::Lambda::Version resource, from the documentation:

creates a version from the current code and configuration of a function. Use versions to create a snapshot of your function code and configuration that doesn't change.

LambdaVersion:
  Type: AWS::Lambda::Version
    Properties: 
      FunctionName: !Ref ApiFunction
      Description: v1

Where the Description property gets fixed because it does not accept updates. Additionally, you can create some aliases for these version like dev, stage, prod. For example, for dev version this would be

DevAlias: 
  Type: AWS::Lambda::Alias 
  Properties: 
    Description: Dev Alias for Lambda function 
    FunctionName: !Ref ApiFunction
    FunctionVersion: !GetAtt LambdaVersion.Version
    Name: DEV