Serverless Plugin Lambda Provisioned Concurrency

A serverless plugin that manages provisioned concurrency for AWS Lambda functions. This plugin allows you to set
provisioned concurrency for specific Lambda versions during deployment and automatically clean it up during removal.

Compatible with Serverless Framework v3 and v4

Features

- Set provisioned concurrency for specific Lambda versions
- Support for both full deployments and single function deployments
- Automatic cleanup during stack removal
- Support for multiple functions configuration
- Flexible version targeting (specific version or latest)
- Automatic management of provisioned concurrency across versions (only one version per function can have provisioned concurrency)
- Error handling and logging

Compatibility

This plugin is compatible with:

- Serverless Framework v3.x
- Serverless Framework v4.x

The plugin automatically detects the Serverless version and adapts its logging and progress reporting accordingly.

Installation

``bash
npm install serverless-plugin-provisioned-concurrency --save-dev
`

Usage

$3

`yaml
plugins:
- serverless-plugin-provisioned-concurrency
`

$3

Add the concurrency configuration directly to your function definitions in serverless.yml:

`yaml
functions:
processor:
handler: src/processor.handler
concurrency:
provisioned: 10
version: '3' # optional - uses latest if not specified
events:
- sqs:
arn: arn:aws:sqs:us-east-1:123456789012:my-queue

api:
handler: src/api.handler
concurrency:
provisioned: 5 # uses latest version
events:
- http:
path: /api
method: get
`

$3

The plugin supports both full deployments and single function deployments:

#### Full deployment

When you run a full deployment with serverless deploy, provisioned concurrency will be set for all configured functions after the stack is updated.

`bash
serverless deploy
`

#### Single function deployment

When you deploy a single function with serverless deploy function, provisioned concurrency will be set for that function if it's configured:

`bash
serverless deploy function -f functionName
`

$3

`yaml
service: my-service

provider:
name: aws
runtime: nodejs18.x
stage: dev
region: us-east-1

plugins:
- serverless-plugin-provisioned-concurrency

functions:
api:
handler: src/api.handler
concurrency:
provisioned: 10 # Uses latest version
events:
- http:
path: /api
method: get

processor:
handler: src/processor.handler
concurrency:
provisioned: 5
version: '3' # Uses specific version 3
events:
- sqs:
arn: arn:aws:sqs:us-east-1:123456789012:my-queue
`

Configuration Options

$3

Each function can include a concurrency section with the following options:

| Option | Type | Required | Default | Description |
| ------------- | ------ | -------- | ------- | -------------------------------------------------------------------------------- |
| provisioned | number | Yes | - | The number of provisioned concurrency units |
| version | string | No | latest | The Lambda version to configure (use specific version number or omit for latest) |

$3

You can configure global settings for the plugin under the custom.provisionedConcurrency section:

| Option | Type | Required | Default | Description |
| ------------ | ------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| maxPercent | number | No | 80 | Maximum percentage of reserved concurrency allowed to be configured as provisioned concurrency. If any function exceeds this limit, the deployment process will be stopped. |

$3

`yaml


Global plugin configuration

custom:
provisionedConcurrency:
maxPercent: 90 # Optional - maximum percentage of reserved concurrency (defaults to 80)

Function configuration

functions:
myFunction:
handler: src/handler.js
reservedConcurrency: 100 # Optional - reserved concurrency for the function
concurrency:
provisioned: 10 # Required - number of concurrent executions
version: '2' # Optional - specific version (defaults to latest)
`

$3

You can specify just the provisioned concurrency if you want to use the latest version:

`yaml
functions:
myFunction:
handler: src/handler.js
concurrency:
provisioned: 10 # Uses latest version
`

How It Works

1. During Validation: The plugin runs before deployment and validates all functions. During this phase, it also manages the deletion of provisioned concurrency from previous versions or when configurations are empty.
2. During Deployment: The plugin runs after the stack is updated and sets provisioned concurrency for the configured functions
3. During Removal: The plugin runs before stack removal and cleans up all provisioned concurrency configurations
4. Version Management: The plugin ensures only one version of a function has provisioned concurrency:
- During the validation phase, the plugin checks if other versions already have provisioned concurrency
- If other versions with provisioned concurrency are found, the plugin automatically removes their provisioned concurrency
- This prevents having multiple versions with provisioned concurrency, which can lead to unexpected costs

Plugin Lifecycle

- Hook: before:deploy:deploy - Validates all functions and manages deletion of provisioned concurrency from previous versions
- Hook: before:deploy:function:deploy - Validates a single function and manages deletion of provisioned concurrency from previous versions
- Hook: after:aws:deploy:deploy:updateStack - Sets provisioned concurrency for all functions
- Hook: after:deploy:function:deploy - Sets provisioned concurrency for a single function

Version Handling

- If no version is specified or version: "latest" is used, the plugin will automatically determine the latest version number
- Specific versions can be targeted by providing the version number as a string
- The plugin will not use the $LATEST pseudo-version as provisioned concurrency cannot be set on it

Error Handling

The plugin includes comprehensive error handling:

- Logs detailed error messages for debugging
- Validates all functions before processing and stops the deployment process if any function exceeds the maximum provisioned concurrency limit (throws MaximumConcurrencyError)
- Throws NoVersionFoundError when no versions are found for a function
- Gracefully handles missing functions or versions
- Provides clear status messages during execution

AWS Permissions

Make sure your AWS credentials have the following permissions:

`json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"lambda:GetProvisionedConcurrencyConfig",
"lambda:PutProvisionedConcurrencyConfig",
"lambda:DeleteProvisionedConcurrencyConfig",
"lambda:ListProvisionedConcurrencyConfigs",
"lambda:ListVersionsByFunction"
],
"Resource": "*"
}
]
}
`

Development

$3

- Node.js >= 22.0.0
- npm or yarn

$3

1. Clone the repository
2. Install dependencies: npm install
3. Build the project: npm run build
4. Run linting: npm run lint
5. Format code: npm run format

$3

This plugin is written in TypeScript for improved type safety and developer experience. The TypeScript source code is compiled to JavaScript during the build process.

- Source code: src/index.ts
- Compiled output: dist/index.js
- Type definitions: dist/index.d.ts

To make changes to the plugin:

1. Edit the TypeScript source files
2. Run npm run build` to compile
3. Test your changes

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details