This plugin facilitates the management of multiple Lambda function versions and seamlessly updates API Gateway endpoints to reference the appropriate alias.

Key features:

• Automatically creates and maintains Lambda aliases corresponding to deployment stages.
• Redirects API Gateway integrations to the appropriate Lambda function aliases.
• Supports both HTTP (REST API) and WebSocket API Gateway events.
• Handles mixed services with both HTTP and WebSocket events simultaneously.
• Handles Lambda permission configuration for API Gateway invocations.
• Ensures API Gateway method settings are properly validated.

Installation

npm install --save-dev serverless-aws-alias-v4

Usage

Add the plugin to your serverless.yml file:

plugins:
  - serverless-aws-alias-v4

Configure the plugin in your serverless.yml file:

custom:
  alias: dev

If the alias property is not defined, the plugin will use the stage name specified in the provider section as a fallback.

provider:
  stage: dev

API Gateway Configuration

This plugin supports both HTTP (REST API) and WebSocket event types:

HTTP API Gateway

functions:
  hello:
    handler: handler.hello
    events:
      - http:
          path: hello
          method: GET

For HTTP APIs, you can specify a REST API ID in your provider configuration:

provider:
  apiGateway:
    restApiId: abcdef123456

WebSocket API Gateway

functions:
  connect:
    handler: handler.connect
    events:
      - websocket: $connect

  disconnect:
    handler: handler.disconnect
    events:
      - websocket: $disconnect

  default:
    handler: handler.default
    events:
      - websocket: $default

  # Custom route
  message:
    handler: handler.message
    events:
      - websocket:
          route: sendMessage

For WebSocket APIs, you can specify a WebSocket API ID in your provider configuration:

provider:
  websocketApiId: wxyz987654

You can mix both HTTP and WebSocket events in the same service, and the plugin will handle both types correctly.

Excluding Functions

To exclude specific functions from alias management:

custom:
  alias:
    name: dev
    excludedFunctions:
      - some-function
# or (will fallback to provider stage)
  alias:
    excludedFunctions:
      - some-function

If you're using the serverless-plugin-warmup plugin alongside this plugin and don't want to create an alias for the warmup function, make sure to add it to your excluded functions configuration:

custom:
  alias:
    name: dev
    excludedFunctions:
      - warmUpPluginDefault
# or (will fallback to provider stage)
  alias:
    excludedFunctions:
      - warmUpPluginDefault

Plugin Compatibility and Limitations

When using this plugin, be aware of the following compatibility considerations:

• Incompatible Plugin: This plugin is not compatible with the serverless-iam-roles-per-function plugin.
• Alternative Recommendation: If you need custom IAM roles, we recommend using serverless-iam-roles-per-function-v4, which works seamlessly with this plugin.

Debugging

By default, only error messages are displayed. To view detailed logs, use one of these methods:

• Set the environment variable SLS_DEBUG=*
• Use the --verbose or -v flag when deploying: sls deploy --verbose
• Enable verbose logging in your custom configuration:

custom:
  alias:
    name: dev
    verbose: true
# or (will fallback to provider stage)
  alias:
    verbose: true

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Contributing

Contributions are welcome! Feel free to submit a pull request or open an issue.