Serverless Framework Configuration

Serverless framework configuration files

Type object
File match serverless.yml
Schema URL https://catalog.lintel.tools/schemas/schemastore/serverless-framework-configuration/latest.json
Source https://raw.githubusercontent.com/lalcebo/json-schema/master/serverless/reference.json

Validate with Lintel

npx @lintel/lintel check
Type: object

Schema for serverless framework configuration files

Properties

provider object required

Configuration for Serverless AWS

46 nested properties
name string required
Values: "aws"
alb AwsAlb
ecr object
2 nested properties
scanOnPush boolean

Enabling this will make AWS scan image for CVE(Common Vulnerabilities and Exposures)

images Record<string, object | object>
apiGateway object
13 nested properties
apiKeySourceType string
Values: "HEADER" "AUTHORIZER"
binaryMediaTypes string[]

Optional binary media types the API might return

description string
minimumCompressionSize number
min=0max=10485760
restApiId string
restApiResources Record<string, string>
restApiRootResourceId string
websocketApiId string
disableDefaultEndpoint boolean

Disable the default 'execute-api' HTTP endpoint (default: false)

apiKeys string | object[]
metrics boolean
shouldStartNameWithService boolean

Use ${service}-${stage} naming for API Gateway. Will be true by default in v3.

usagePlan object
2 nested properties
quota object
throttle object
apiKeys string[]
apiName string

Change this to use a custom name for the API Gateway API

cfnRole string
deploymentBucket object

Configure the S3 bucket used by Serverless Framework to deploy code packages to Lambda

11 nested properties
blockPublicAccess boolean

Prevents public access via ACLs or bucket policies (default: false). Note: the deployment bucket is not public by default. These are additional ACLs.

maxPreviousDeploymentArtifacts string | number

On deployment, serverless prunes artifacts older than this limit (default: 5)

name string

Name of an existing bucket to use (default: created by serverless)

serverSideEncryption string
sseCustomerAlgorithim string
sseCustomerKey string
sseCustomerKeyMD5 string
sseKMSKeyId string
tags Record<string, string>
skipPolicySetup boolean

Skip the creation of a default bucket policy when the deployment bucket is created (default: false)

versioning boolean

Enable bucket versioning (default: false)

deploymentPrefix string
endpointType string
Values: "EDGE" "PRIVATE" "REGIONAL"
environment Record<string, any>
httpApi AwsHttpApi
iam AwsIamConfiguration
iamManagedPolicies string[]
iamRoleStatements AwsIamRoleStatement[]
logRetentionInDays string | number
logs object
4 nested properties
frameworkLambda boolean
httpApi AwsHttpApiLogs | boolean
restApi object
7 nested properties
accessLogging boolean
executionLogging boolean
format string
fullExecutionData boolean
level string
role string
roleManagedExternally boolean
websocket object
5 nested properties
level string
Values: "INFO" "ERROR"
format string

Log format to use for access logs. Ref:- https://docs.aws.amazon.com/apigateway/latest/developerguide/websocket-api-logging.html

accessLogging boolean

Enables HTTP access logs (default: true)

executionLogging boolean

Enable execution logging (default: true)

fullExecutionData boolean

Log full requests/responses for execution logging (default: true)

memorySize string | number
One of: string string, number number
notificationArns string[]
profile string
region AwsRegion
reservedConcurrency string | number
resourcePolicy AwsResourcePolicy[]
role string
rolePermissionsBoundary string
rollbackConfiguration object
2 nested properties
MonitoringTimeInMinutes string | number
RollbackTriggers AwsRollbackTrigger[]
runtime AwsRuntime
stackName string
stackParameters AwsStackParameters[]
stackPolicy AwsResourcePolicy[]
stackTags Record<string, string>
stage string
tags Record<string, string>
timeout string | number
tracing object
2 nested properties
apiGateway boolean
lambda boolean
usagePlan object
2 nested properties
quota object
3 nested properties
limit string | number
offset string | number
period string
throttle object
2 nested properties
burstLimit string | number
rateLimit string | number
versionFunctions boolean

Use function versioning (enabled by default)

architecture AwsSupportedArchitecture
vpc object
2 nested properties
securityGroupIds Aws_CF_Function | string[] required
subnetIds Aws_CF_Function | string[] required
websocketsApiName string
websocketsApiRouteSelectionExpression string
websocketsDescription string
deploymentMethod string

Method used for CloudFormation deployments: 'changesets' or 'direct' (default: changesets). See https://www.serverless.com/framework/docs/providers/aws/guide/deploying#deployment-method

Values: "direct" "changesets"
disableRollback boolean

Disable automatic rollback by CloudFormation on failure. To be used for non-production environments.

logDataProtectionPolicy LogDataProtectionPolicy
runtimeManagement AwsLambdaRuntimeManagement
service ServerlessServiceConfiguration | string required
app string
custom object
7 nested properties
pythonRequirements PythonRequirements
wsgi PythonWsgi
prune Prune
esbuild Esbuild
splitStacks SplitStacks
webpack WebpackConfiguration
ssmPublish SsmPublishConfiguration
frameworkVersion string
functions object | string | ServerlessFilePath[]
layers AwsLayers
org string
package AwsPackage
plugins string[] | object
tenant string
stepFunctions AwsStepFunctions

Definitions

Transform object
AwsAlexaSmartHome object
appId string
enabled boolean
AwsApiGateway object
apiKeySourceType string
Values: "HEADER" "AUTHORIZER"
binaryMediaTypes string[]

Optional binary media types the API might return

description string
minimumCompressionSize number
min=0max=10485760
restApiId string
restApiResources Record<string, string>
restApiRootResourceId string
websocketApiId string
disableDefaultEndpoint boolean

Disable the default 'execute-api' HTTP endpoint (default: false)

apiKeys string | object[]
metrics boolean
shouldStartNameWithService boolean

Use ${service}-${stage} naming for API Gateway. Will be true by default in v3.

usagePlan object
2 nested properties
quota object
3 nested properties
limit number
offset number
period string
throttle object
2 nested properties
burstLimit number
rateLimit number
AwsFunction object
awsKmsKeyArn string
condition string
dependsOn string[]
description string
destinations object
2 nested properties
onFailure string
onSuccess string
environment Record<string, any>
events AwsEvent[]
handler string
layers string | FnRef | FnGetAtt | FnJoin | FnTransform | FnFindInMap[]

Collection of Lambda layers to make it available for this lambda. Can use Cloudformation here as well. Usage on:- https://www.serverless.com/framework/docs/providers/aws/guide/layers#using-your-layers

memorySize string | number
name string
onError string
package AwsPackage
provisionedConcurrency integer | Aws_CF_FunctionString | FnIf
reservedConcurrency integer | Aws_CF_FunctionString | FnIf
role string
runtime AwsRuntime
tags Record<string, string>
timeout string | number
tracing string
vpc object
2 nested properties
securityGroupIds Aws_CF_Function | string[] required
subnetIds Aws_CF_Function | string[] required
image string | object
snapStart boolean

https://www.serverless.com/framework/docs/providers/aws/guide/functions#snapstart

logDataProtectionPolicy LogDataProtectionPolicy
runtimeManagement AwsLambdaRuntimeManagement
AwsCloudFront object
eventType string
includeBody boolean
origin object
3 nested properties
CustomOriginConfig object
1 nested properties
OriginProtocolPolicy string
DomainName string
OriginPath string
pathPattern string
AwsCloudwatchLog object
filter string
logGroup string
AwsCognitoUserPool object
existing boolean
pool string
trigger string
ServerlessCustom object
pythonRequirements PythonRequirements
wsgi PythonWsgi
prune Prune
esbuild Esbuild
splitStacks SplitStacks
webpack WebpackConfiguration
ssmPublish SsmPublishConfiguration
AwsDeploymentBucket object

Configure the S3 bucket used by Serverless Framework to deploy code packages to Lambda

blockPublicAccess boolean

Prevents public access via ACLs or bucket policies (default: false). Note: the deployment bucket is not public by default. These are additional ACLs.

maxPreviousDeploymentArtifacts string | number

On deployment, serverless prunes artifacts older than this limit (default: 5)

name string

Name of an existing bucket to use (default: created by serverless)

serverSideEncryption string
sseCustomerAlgorithim string
sseCustomerKey string
sseCustomerKeyMD5 string
sseKMSKeyId string
tags Record<string, string>
skipPolicySetup boolean

Skip the creation of a default bucket policy when the deployment bucket is created (default: false)

versioning boolean

Enable bucket versioning (default: false)

AwsDestinations object
onFailure string
onSuccess string
AwsDetail Record<string, string[]>
AwsEnvironment Record<string, any>
AwsEvent object
activemq AwsActiveMq
alb AwsAlbEvent
alexaSkill AwsAlexaSkill
alexaSmartHome object
2 nested properties
appId string
enabled boolean
cloudFront object
4 nested properties
eventType string
includeBody boolean
origin object
3 nested properties
CustomOriginConfig object
DomainName string
OriginPath string
pathPattern string
cloudwatchEvent AwsCloudwatchEvent
cloudwatchLog object
2 nested properties
filter string
logGroup string
cognitoUserPool object
3 nested properties
existing boolean
pool string
trigger string
eventBridge object

Aws Lambda function Eventbridge event source

Any of: variant, variant
9 nested properties
eventBus string
minLength=1
schedule string
pattern=^(?:cron|rate)\(.+\)$
name string
minLength=1maxLength=64pattern=[a-zA-Z0-9-_.]+
enabled boolean
Default: true
pattern AwsPatternExisting | AwsPatternInput
input object
inputPath string
minLength=1maxLength=256
inputTransformer AwsInputTransformer
retryPolicy object
2 nested properties
maximumEventAge number
min=60max=86400
maximumRetryAttempts number
min=0max=185
http object | string
httpApi object | string
iot object
5 nested properties
description string
enabled boolean
name string
sql string
sqlVersion string
s3 object | string
schedule AwsScheduleEvent | string
sns AwsSns
sqs AwsSqs | string
stream object
4 nested properties
arn Aws_CF_Function
batchSize string | number
enabled boolean
startingPosition string | number
websocket object
3 nested properties
authorizer object
3 nested properties
arn string
identitySource string[]
name string
route string
routeResponseSelectionExpression string
AwsEventBridge object

Aws Lambda function Eventbridge event source

eventBus string
minLength=1
schedule string
pattern=^(?:cron|rate)\(.+\)$
name string
minLength=1maxLength=64pattern=[a-zA-Z0-9-_.]+
enabled boolean
Default: true
pattern AwsPatternExisting | AwsPatternInput
input object
inputPath string
minLength=1maxLength=256
inputTransformer AwsInputTransformer
retryPolicy object
2 nested properties
maximumEventAge number
min=60max=86400
maximumRetryAttempts number
min=0max=185
AwsFunctions object | string | ServerlessFilePath[]
AwsHttp object | string
AwsHttpApiEvent object | string
AwsHttpApiLogs object
format string
AwsHttpAuthorizer string | object | object | object | object
AwsHttpRequestParametersValidation object
headers Record<string, boolean>
paths Record<string, boolean>
querystrings Record<string, boolean>
AwsHttpRequestValidation object
parameters object
3 nested properties
headers Record<string, boolean>
paths Record<string, boolean>
querystrings Record<string, boolean>
schema Record<string, string>
AwsIdRefHttpApiEventAuthorizer object
id string
scopes string[]
AwsIot object
description string
enabled boolean
name string
sql string
sqlVersion string
AwsLogs object
frameworkLambda boolean
httpApi AwsHttpApiLogs | boolean
restApi object
7 nested properties
accessLogging boolean
executionLogging boolean
format string
fullExecutionData boolean
level string
role string
roleManagedExternally boolean
websocket object
5 nested properties
level string
Values: "INFO" "ERROR"
format string

Log format to use for access logs. Ref:- https://docs.aws.amazon.com/apigateway/latest/developerguide/websocket-api-logging.html

accessLogging boolean

Enables HTTP access logs (default: true)

executionLogging boolean

Enable execution logging (default: true)

fullExecutionData boolean

Log full requests/responses for execution logging (default: true)

AwsNamedHttpApiEventAuthorizer object
name string
scopes string[]
AwsOrigin object
CustomOriginConfig object
1 nested properties
OriginProtocolPolicy string
DomainName string
OriginPath string
AwsPatternExisting object
source string[]
AwsPatternInput object
detail Record<string, string[]>
detail-type string[]
source string[]
AwsProvider object

Configuration for Serverless AWS

name string required
Values: "aws"
alb AwsAlb
ecr object
2 nested properties
scanOnPush boolean

Enabling this will make AWS scan image for CVE(Common Vulnerabilities and Exposures)

images Record<string, object | object>
apiGateway object
13 nested properties
apiKeySourceType string
Values: "HEADER" "AUTHORIZER"
binaryMediaTypes string[]

Optional binary media types the API might return

description string
minimumCompressionSize number
min=0max=10485760
restApiId string
restApiResources Record<string, string>
restApiRootResourceId string
websocketApiId string
disableDefaultEndpoint boolean

Disable the default 'execute-api' HTTP endpoint (default: false)

apiKeys string | object[]
metrics boolean
shouldStartNameWithService boolean

Use ${service}-${stage} naming for API Gateway. Will be true by default in v3.

usagePlan object
2 nested properties
quota object
throttle object
apiKeys string[]
apiName string

Change this to use a custom name for the API Gateway API

cfnRole string
deploymentBucket object

Configure the S3 bucket used by Serverless Framework to deploy code packages to Lambda

11 nested properties
blockPublicAccess boolean

Prevents public access via ACLs or bucket policies (default: false). Note: the deployment bucket is not public by default. These are additional ACLs.

maxPreviousDeploymentArtifacts string | number

On deployment, serverless prunes artifacts older than this limit (default: 5)

name string

Name of an existing bucket to use (default: created by serverless)

serverSideEncryption string
sseCustomerAlgorithim string
sseCustomerKey string
sseCustomerKeyMD5 string
sseKMSKeyId string
tags Record<string, string>
skipPolicySetup boolean

Skip the creation of a default bucket policy when the deployment bucket is created (default: false)

versioning boolean

Enable bucket versioning (default: false)

deploymentPrefix string
endpointType string
Values: "EDGE" "PRIVATE" "REGIONAL"
environment Record<string, any>
httpApi AwsHttpApi
iam AwsIamConfiguration
iamManagedPolicies string[]
iamRoleStatements AwsIamRoleStatement[]
logRetentionInDays string | number
logs object
4 nested properties
frameworkLambda boolean
httpApi AwsHttpApiLogs | boolean
restApi object
7 nested properties
accessLogging boolean
executionLogging boolean
format string
fullExecutionData boolean
level string
role string
roleManagedExternally boolean
websocket object
5 nested properties
level string
Values: "INFO" "ERROR"
format string

Log format to use for access logs. Ref:- https://docs.aws.amazon.com/apigateway/latest/developerguide/websocket-api-logging.html

accessLogging boolean

Enables HTTP access logs (default: true)

executionLogging boolean

Enable execution logging (default: true)

fullExecutionData boolean

Log full requests/responses for execution logging (default: true)

memorySize string | number
One of: string string, number number
notificationArns string[]
profile string
region AwsRegion
reservedConcurrency string | number
resourcePolicy AwsResourcePolicy[]
role string
rolePermissionsBoundary string
rollbackConfiguration object
2 nested properties
MonitoringTimeInMinutes string | number
RollbackTriggers AwsRollbackTrigger[]
runtime AwsRuntime
stackName string
stackParameters AwsStackParameters[]
stackPolicy AwsResourcePolicy[]
stackTags Record<string, string>
stage string
tags Record<string, string>
timeout string | number
tracing object
2 nested properties
apiGateway boolean
lambda boolean
usagePlan object
2 nested properties
quota object
3 nested properties
limit string | number
offset string | number
period string
throttle object
2 nested properties
burstLimit string | number
rateLimit string | number
versionFunctions boolean

Use function versioning (enabled by default)

architecture AwsSupportedArchitecture
vpc object
2 nested properties
securityGroupIds Aws_CF_Function | string[] required
subnetIds Aws_CF_Function | string[] required
websocketsApiName string
websocketsApiRouteSelectionExpression string
websocketsDescription string
deploymentMethod string

Method used for CloudFormation deployments: 'changesets' or 'direct' (default: changesets). See https://www.serverless.com/framework/docs/providers/aws/guide/deploying#deployment-method

Values: "direct" "changesets"
disableRollback boolean

Disable automatic rollback by CloudFormation on failure. To be used for non-production environments.

logDataProtectionPolicy LogDataProtectionPolicy
runtimeManagement AwsLambdaRuntimeManagement
AwsQuota object
limit string | number
offset string | number
period string
AwsResourcePolicy object
Action string[] | object | string
Condition Record<string, any>
Effect string
Values: "Allow" "Deny"
Principal string[] | object | string
Resource string[] | object | string
ServerlessFrameworkResources object | ServerlessFilePath
ServerlessFilePath string
AwsRestApiLogs object
accessLogging boolean
executionLogging boolean
format string
fullExecutionData boolean
level string
role string
roleManagedExternally boolean
AwsRollbackConfiguration object
MonitoringTimeInMinutes string | number
RollbackTriggers AwsRollbackTrigger[]
AwsRollbackTrigger object
Arn string
Type string
AwsS3 object | string
AwsS3Rule object
prefix string
suffix string
ServerlessServiceConfiguration object

@deprecated and doesn't work in serverless framework v3

awsKmsKeyArn string
name string
AwsStackParameters object
ParameterKey string
ParameterValue string
AwsStream object
arn Aws_CF_Function
batchSize string | number
enabled boolean
startingPosition string | number
AwsTags Record<string, string>
AwsThrottle object
burstLimit string | number
rateLimit string | number
AwsTracing object
apiGateway boolean
lambda boolean
AwsUsagePlan object
quota object
3 nested properties
limit string | number
offset string | number
period string
throttle object
2 nested properties
burstLimit string | number
rateLimit string | number
AwsVpc object
securityGroupIds Aws_CF_Function | string[] required
subnetIds Aws_CF_Function | string[] required
AwsWebsocket object
authorizer object
3 nested properties
arn string
identitySource string[]
name string
route string
routeResponseSelectionExpression string
AwsWebsocketAuthorizer object
arn string
identitySource string[]
name string
AwsWebsocketLogs object
level string
Values: "INFO" "ERROR"
format string

Log format to use for access logs. Ref:- https://docs.aws.amazon.com/apigateway/latest/developerguide/websocket-api-logging.html

accessLogging boolean

Enables HTTP access logs (default: true)

executionLogging boolean

Enable execution logging (default: true)

fullExecutionData boolean

Log full requests/responses for execution logging (default: true)