<!--
title: Serverless Framework - AWS Lambda Guide - Serverless.yml Reference
menuText: Serverless.yml
menuOrder: 16
description: A list of all available properties on serverless.yml for AWS
layout: Doc
-->

<!-- DOCS-SITE-LINK:START automatically generated  -->

### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/aws/guide/serverless.yml)

<!-- DOCS-SITE-LINK:END -->

# Serverless.yml Reference

Here is a list of all available properties in `serverless.yml` when the provider is set to `aws`.

## Root properties

```yml
# serverless.yml

# Org name
# This is your Serverless Framework Organization, often named after your company or team.
# This is tied to your user account or license key.
# This is optional. A default org is auto-set within your .serverlessrc file in your root directory, but recommended to ensure you are always deploying to the correct org.
org: my-org

# App name
# The "App" concept acts as a parent container for one or more "Services," which you can configure via the `app` property in `serverless.yml`.
# Setting an `app` activates Serverless Framework Dashboard features for that Service, such as tracking deployments, sharing outputs and secrets, and enabling metrics, traces, and logs.
# This is optional. If you don't want to use Dashboard features, don't set this.
app: my-app

# Service name
# This is the name of your project/app/service/microservice (it's scope is up to you).
service: my-service
```

### Stages

Use the `stages` property to specify stage-specific configuration, like `params`, and `observability` settings.

#### Parameters

```yml
# serverless.yml
service: billing

stages:
  prod:
    # Enables observability in the prod stage
    observability: true

    # Sepcify parameter values to be used in the prod stage
    params:
      stripe_api_key: ${env:PROD_STRIPE_API_KEY}

  default:
    # Disabales observability in all other stages
    observability: false

    # Sepcify parameter values to be used in all other stages
    params:
      stripe_api_key: ${env:DEV_STRIPE_API_KEY}
```

### Parameters

Learn more about stage parameters in the [Parameters documentation](../../../guides/parameters.md).

```yml
# serverless.yml

# Stage parameters
# Parameters are Stage-specific values you can reference elsewhere in your YAML via ${param:my-value}
# Parameters can be defined in `serverless.yml` (and Dashboard and CLI options)
# "default" Parameters are available across all Stages.
# Otherwise, Stage-specific Parameters can be set here.
params:
  default:
    domain: ${sls:stage}.myapi.com
  prod:
    domain: myapi.com
  dev:
    domain: dev.myapi.com

# Example usage
# This will change depending on the Stage set.
foo: ${param:domain}
```

**Note:** Specifying parameters under the `stage` property as shown in the previous section is the preferred way of setting parameters in v4 of the Serverless Framework.

## Provider

Use this block to specify Service-wide AWS-specific details.

### General settings

```yml
# serverless.yml

provider:
  # Name of the Provider. Note, V.4 only supports AWS.
  name: aws
  # Default stage. Optional. (default: dev)
  stage: dev
  # Default region. Optional. (default: us-east-1)
  region: us-east-1
  # The local AWS profile to use to deploy. Optional. (default: "default" profile)
  profile: production
  # Use a custom name for the CloudFormation stack. Optional.
  stackName: custom-stack-name
  # CloudFormation tags to apply to APIs and functions. Optional.
  tags:
    foo: bar
    baz: qux
  # CloudFormation tags to apply to the stack. Optional.
  stackTags:
    key: value
  # Method used for CloudFormation deployments: 'changesets' or 'direct'. Optional. (default: changesets)
  # See https://www.serverless.com/framework/docs/providers/aws/guide/deploying#deployment-method
  deploymentMethod: direct
  # List of existing Amazon SNS topics in the same region where notifications about stack events are sent. Optional.
  notificationArns:
    - 'arn:aws:sns:us-east-1:XXXXXX:mytopic'
  # AWS Cloudformation Stack Parameters. Optional.
  stackParameters:
    - ParameterKey: 'Keyname'
      ParameterValue: 'Value'
  # Disable automatic rollback by CloudFormation on failure. To be used for non-production environments. Optional.
  disableRollback: true
  # AWS Cloudformation Rollback configuration. Optional.
  rollbackConfiguration:
    MonitoringTimeInMinutes: 20
    RollbackTriggers:
      - Arn: arn:aws:cloudwatch:us-east-1:000000000000:alarm:health
        Type: AWS::CloudWatch::Alarm
      - Arn: arn:aws:cloudwatch:us-east-1:000000000000:alarm:latency
        Type: AWS::CloudWatch::Alarm
  # AWS X-Ray Tracing Configuration. Optional.
  tracing:
    # Can only be true if API Gateway is inside a stack.
    apiGateway: true
    # Can be true (true equals 'Active'), 'Active' or 'PassThrough'
    lambda: true
```

### General AWS Lambda settings

Some AWS Lambda function settings can be defined for all functions inside the `provider` key:

```yml
# serverless.yml

provider:
  # AWS Lambda runtime for all AWS Lambda functions within the Service. Optional.
  runtime: nodejs20.x
  # Set how Lambda controls all functions runtime. AWS default is auto; this can either be 'auto' or 'onFunctionUpdate'. For 'manual', see example in hello function below (syntax for both is identical. Optional.
  runtimeManagement: auto
  # Default memory size for functions. Optional. (default: 1024MB).
  memorySize: 512
  # Default timeout for functions. Optional. (default: 6 seconds).
  # Note: API Gateway has a maximum timeout of 30 seconds
  timeout: 10
  # AWS Lambda Environment Variables for all functions. Optional.
  environment:
    APP_ENV_VARIABLE: FOOBAR
  # Duration for CloudWatch log retention. Optional. (default: forever).
  # Can be overridden for each function separately inside the functions block, see below on page.
  # Valid values: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-loggroup.html
  logRetentionInDays: 14
  # Policy defining how to monitor and mask sensitive data in CloudWatch logs. Optional.
  # Policy format: https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/mask-sensitive-log-data-start.html
  logDataProtectionPolicy:
    Name: data-protection-policy
  # KMS key ARN to use for encryption for all AWS Lambda functions. Optional.
  kmsKeyArn: arn:aws:kms:us-east-1:XXXXXX:key/some-hash
  # Version of hashing algorithm used by Serverless Framework for AWS Lambda function packaging. Optional.
  lambdaHashingVersion: 20201221
  # Use AWS Lambda function versioning. Optional. (enabled by default)
  versionFunctions: false
  # AWS Lambda Processor architecture: 'x86_64' or 'arm64' via Graviton2. Optional. (default: x86_64)
  architecture: x86_64
```

### Deployment bucket

Serverless Framework needs an AWS S3 bucket to store artifacts for deploying.

That bucket is automatically created and managed by Serverless, but you can configure it explicitly if needed:

```yaml
provider:
  # The S3 prefix under which deployed artifacts are stored. Optional. (default: serverless)
  deploymentPrefix: serverless
  # Configure the S3 bucket used by Serverless Framework to deploy code packages to Lambda. Optional.
  deploymentBucket:
    # Name of an existing bucket to use. Optional. (default: created by serverless)
    name: com.serverless.${self:provider.region}.deploys
    # On deployment, serverless prunes artifacts older than this limit (default: 5)
    maxPreviousDeploymentArtifacts: 10
    # Prevents public access via ACLs or bucket policies (default: false)
    # Note: the deployment bucket is not public by default. These are additional ACLs.
    blockPublicAccess: true
    # Skip the creation of a default bucket policy when the deployment bucket is created (default: false)
    skipPolicySetup: true
    # Enable bucket versioning (default: false)
    versioning: true
    # Server-side encryption method
    serverSideEncryption: AES256
    # For server-side encryption
    sseKMSKeyId: arn:aws:kms:us-east-1:xxxxxxxxxxxx:key/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa
    # For server-side encryption with custom keys
    sseCustomerAlgorithim: AES256
    sseCustomerKey: string
    sseCustomerKeyMD5: md5sum
    # Tags that will be added to each of the deployment resources
    tags:
      key1: value1
      key2: value2
```

### API Gateway v2 HTTP API

The `httpApi` settings apply to [API Gateway v2 HTTP APIs](../events/http-api.md):

```yml
provider:
  httpApi:
    # Attach to an externally created HTTP API via its ID:
    id: xxxx
    # Set a custom name for the API Gateway API (default: ${sls:stage}-${self:service})
    name: dev-my-service
    # Payload format version (note: use quotes in YAML: '1.0' or '2.0') (default: '2.0')
    payload: '2.0'
    # Disable the default 'execute-api' HTTP endpoint (default: false)
    # Useful when using a custom domain.
    disableDefaultEndpoint: true
    # Enable detailed CloudWatch metrics (default: false)
    metrics: true
    # Enable CORS HTTP headers with default settings (allow all)
    # Can be fine-tuned with specific options
    cors: true
    authorizers:
      # JWT API authorizer
      someJwtAuthorizer:
        identitySource: $request.header.Authorization
        issuerUrl: https://cognito-idp.us-east-1.amazonaws.com/us-east-1_xxxxx
        audience:
          - xxxx
          - xxxx
      # Custom Lambda request authorizer
      someCustomLambdaAuthorizer:
        # Should be set to 'request' for custom Lambda authorizers
        type: request
        # Mutually exclusive with `functionArn`
        functionName: authorizerFunc
        # Mutually exclusive with `functionName`
        functionArn: arn:aws:lambda:us-east-1:11111111111:function:external-authorizer
        # Optional. Custom name for created authorizer
        name: customAuthorizerName
        # Optional. Time to live for cached authorizer results, accepts values from 0 (no caching) to 3600 (1 hour)
        # When set to non-zero value, 'identitySource' must be defined as well
        resultTtlInSeconds: 300
        # Set if authorizer function will return authorization responses in simple format (default: false)
        enableSimpleResponses: true
        # Version of payload that will be sent to authorizer function (default: '2.0')
        payloadVersion: '2.0'
        # Optional. One or more mapping expressions of the request parameters in form of e.g `$request.header.Auth`.
        # Specified values are verified to be non-empty and not null by authorizer.
        # It is a required property when `resultTtlInSeconds` is non-zero as `identitySource` is additionally
        # used as cache key for authorizer responses caching.
        identitySource:
          - $request.header.Auth
          - $request.header.Authorization
        # Optional. Applicable only when using externally defined authorizer functions
        # to prevent creation of permission resource
        managedExternally: true
```

### API Gateway v1 REST API

The `apiGateway` settings apply to [API Gateway v1 REST APIs](../events/apigateway.md) and [websocket APIs](../events/websocket.md):

```yml
provider:
  # Use a custom name for the API Gateway API
  apiName: custom-api-name
  # Endpoint type for API Gateway REST API: edge or regional (default: edge)
  endpointType: REGIONAL
  # Use a custom name for the websockets API
  websocketsApiName: custom-websockets-api-name
  # custom route selection expression
  websocketsApiRouteSelectionExpression: $request.body.route
  # Use a custom description for the websockets API
  websocketsDescription: Custom Serverless Websockets
  # Optional API Gateway REST API global config
  apiGateway:
    # Attach to an externally created REST API via its ID:
    restApiId: xxxx
    # Root resource ID, represent as / path
    restApiRootResourceId: xxxx
    # List of existing resources that were created in the REST API. This is required or the stack will be conflicted
    restApiResources:
      '/users': xxxx
      '/users/create': xxxx
    # Attach to an externally created Websocket API via its ID:
    websocketApiId: xxxx
    # Disable the default 'execute-api' HTTP endpoint (default: false)
    disableDefaultEndpoint: true
    # Source of API key for usage plan: HEADER or AUTHORIZER
    apiKeySourceType: HEADER
    # List of API keys for the REST API
    apiKeys:
      - name: myFirstKey
        value: myFirstKeyValue
        description: myFirstKeyDescription
        customerId: myFirstKeyCustomerId
        # Can be used to disable the API key without removing it (default: true)
        enabled: false
      - ${sls:stage}-myFirstKey
      - ${env:MY_API_KEY} # you can hide it in a serverless variable
    # Compress response when larger than specified size in bytes (must be between 0 and 10485760)
    minimumCompressionSize: 1024
    # Description for the API Gateway stage deployment
    description: Some description
    # Optional binary media types the API might return
    binaryMediaTypes:
      - '*/*'
    # Optional detailed Cloud Watch Metrics
    metrics: false
    # Use `${service}-${stage}` naming for API Gateway. Will be `true` by default in v3.
    shouldStartNameWithService: false
    resourcePolicy:
      - Effect: Allow
        Principal: '*'
        Action: execute-api:Invoke
        Resource:
          - execute-api:/*/*/*
        Condition:
          IpAddress:
            aws:SourceIp:
              - '123.123.123.123'
    # Optional usage plan configuration
    usagePlan:
      quota:
        limit: 5000
        offset: 2
        period: MONTH
      throttle:
        burstLimit: 200
        rateLimit: 100
    request:
      # Request schema validation models that can be reused in `http` events
      # It is always defined for `application/json` content type
      schemas:
        global-model:
          # JSON Schema
          schema: ${file(schema.json)}
          # Optional: Name of the API Gateway model
          name: GlobalModel
          # Optional: Description of the API Gateway model
          description: 'A global model that can be referenced in functions'
```

### ALB

Configure [Application Load Balancer](../events/alb.md):

```yml
provider:
  alb:
    # Optional prefix to prepend when generating names for target groups
    targetGroupPrefix: xxxx
    authorizers:
      myFirstAuth:
        type: 'cognito'
        # Required
        userPoolArn: 'arn:aws:cognito-idp:us-east-1:123412341234:userpool/us-east-1_123412341'
        # Required
        userPoolClientId: '1h57kf5cpq17m0eml12EXAMPLE'
        # Required
        userPoolDomain: your-test-domain
        # If set to 'allow' this allows the request to be forwarded to the target when user is not authenticated.
        # When omitted it defaults 'deny' which makes a HTTP 401 Unauthorized error be returned.
        # Alternatively configure to 'authenticate' to redirect request to IdP authorization endpoint.
        onUnauthenticatedRequest: deny
        # optional. The query parameters (up to 10) to include in the redirect request to the authorization endpoint
        requestExtraParams:
          prompt: login
          redirect: false
        # Combination of any system-reserved scopes or custom scopes associated with the client (default: openid)
        scope: 'first_name age'
        # Name of the cookie used to maintain session information (default: AWSELBAuthSessionCookie)
        sessionCookieName: '🍪'
        # Maximum duration of the authentication session in seconds (default: 604800 seconds/7 days)
        sessionTimeout: 7000
      mySecondAuth:
        type: oidc
        # Required. The authorization endpoint of the IdP.
        # Must be a full URL, including the HTTPS protocol, the domain, and the path
        authorizationEndpoint: 'https://example.com'
        # Required
        clientId: i-am-client
        # If creating a rule this is required
        # If modifying a rule, this can be omitted if you set useExistingClientSecret to true (as below)
        clientSecret: i-am-secret
        # Only required if clientSecret is omitted
        useExistingClientSecret: true
        # Required. The OIDC issuer identifier of the IdP
        # This must be a full URL, including the HTTPS protocol, the domain, and the path
        issuer: 'https://www.iamscam.com'
        # Required
        tokenEndpoint: 'http://somewhere.org'
        # Required
        userInfoEndpoint: 'https://another-example.com'
        # If set to 'allow' this allows the request to be forwarded to the target when user is not authenticated.
        # Omit or set to 'deny' (default) to make a HTTP 401 Unauthorized error be returned instead.
        # Alternatively configure to 'authenticate' to redirect request to IdP authorization endpoint.
        onUnauthenticatedRequest: 'deny'
        requestExtraParams:
          prompt: login
          redirect: false
        scope: first_name age
        sessionCookieName: '🍪'
        sessionTimeout: 7000
```

### Docker image deployments in ECR

Configure [deployment via Docker images](./functions.md#referencing-container-image-as-a-target):

```yaml
provider:
  ecr:
    scanOnPush: true
    # Definitions of images that later can be referenced by key in `function.image`
    images:
      baseimage:
        # URI of an existing Docker image in ECR
        uri: 000000000000.dkr.ecr.us-east-1.amazonaws.com/test-image@sha256:6bb600b4d6e1d7cf521097177d111111ea373edb91984a505333be8ac9455d38
      anotherimage:
        # Path to the Docker context that will be used when building that image locally (default: '.')
        path: ./image/
        # Dockerfile that will be used when building the image locally (default: 'Dockerfile')
        file: Dockerfile.dev
        buildArgs:
          STAGE: ${sls:stage}
        buildOptions:
          [
            '--tag',
            'v1.0.0',
            '--add-host',
            'example.com:0.0.0.0',
            '--ssh',
            'default=/path/to/private/key/id_rsa',
          ]
        cacheFrom:
          - my-image:latest
```

### CloudFront

Configure the CloudFront distribution used for [CloudFront Lambda@Edge events](../events/cloudfront.md):

```yml
provider:
  cloudFront:
    cachePolicies:
      # Used as a reference in function.events[].cloudfront.cachePolicy.name
      myCachePolicy1:
        DefaultTTL: 60
        MinTTL: 30
        MaxTTL: 3600
        Comment: my brand new cloudfront cache policy # optional
        ParametersInCacheKeyAndForwardedToOrigin:
          CookiesConfig:
            # Possible values are 'none', 'whitelist', 'allExcept' and 'all'
            CookieBehavior: whitelist
            Cookies:
              - my-public-cookie
          EnableAcceptEncodingBrotli: true # optional
          EnableAcceptEncodingGzip: true
          HeadersConfig:
            # Possible values are 'none' and 'whitelist'
            HeaderBehavior: whitelist
            Headers:
              - authorization
              - content-type
          QueryStringsConfig:
            # Possible values are 'none', 'whitelist', 'allExcept' and 'all'
            QueryStringBehavior: allExcept
            QueryStrings:
              - not-cached-query-string
```

### IAM permissions

Configure IAM roles and permissions applied to Lambda functions ([complete documentation](./iam.md)):

```yml
provider:
  iam:
    # Instruct Serverless to use an existing IAM role for all Lambda functions
    role: arn:aws:iam::XXXXXX:role/role
    # OR configure the role that will be created by Serverless (simplest):
    role:
      # Add statements to the IAM role to give permissions to Lambda functions
      statements:
        - Effect: Allow
          Action:
            - 's3:ListBucket'
          Resource:
            Fn::Join:
              - ''
              - - 'arn:aws:s3:::'
                - Ref: ServerlessDeploymentBucket
      # Optional custom name for default IAM role
      name: your-custom-name-role
      # Optional custom path for default IAM role
      path: /your-custom-path/
      # Optional IAM Managed Policies to include into the IAM Role
      managedPolicies:
        - arn:aws:iam:*****:policy/some-managed-policy
      # ARN of a Permissions Boundary for the role
      permissionsBoundary: arn:aws:iam::XXXXXX:policy/policy
      # CloudFormation tags
      tags:
        key: value
    # ARN of an IAM role for CloudFormation service. If specified, CloudFormation uses the role's credentials
    deploymentRole: arn:aws:iam::XXXXXX:role/role
  # Optional CF stack policy to restrict which resources can be updated/deleted on deployment
  # The example below allows updating all resources in the service except deleting/replacing EC2 instances (use with caution!)
  stackPolicy:
    - Effect: Allow
      Principal: '*'
      Action: 'Update:*'
      Resource: '*'
    - Effect: Deny
      Principal: '*'
      Resource: '*'
      Action:
        - Update:Replace
        - Update:Delete
      Condition:
        StringEquals:
          ResourceType:
            - AWS::EC2::Instance
```

### VPC

Configure the Lambda functions to run inside a VPC ([complete documentation](./functions.md#vpc-configuration)):

```yml
provider:
  # Optional VPC settings
  # If you use VPC then both securityGroupIds and subnetIds are required
  vpc:
    securityGroupIds:
      - securityGroupId1
      - securityGroupId2
    subnetIds:
      - subnetId1
      - subnetId2
```

### Logs

Configure logs for the deployed resources:

```yml
provider:
  logs:
    # Optional Configuration of Lambda Logging Configuration
    lambda:
      # The Log Format to be used for all lambda functions (default: Text)
      logFormat: JSON
      # The Application Log Level to be used, This can only be set if `logFormat` is set to `JSON`
      applicationLogLevel: ERROR
      # The System Log Level to be used, This can only be set if `logFormat` is set to `JSON`
      systemLogLevel: INFO
      # The LogGroup that will be used by default. If this is set the Framework will not create LogGroups for any functions
      logGroup: /aws/lambda/global-log-group

    # Enable HTTP API logs
    # This can either be set to `httpApi: true` to use defaults, or configured via subproperties
    # Can only be configured if the API is created by Serverless Framework
    httpApi:
      format: '{ "requestId":"$context.requestId", "ip": "$context.identity.sourceIp", "requestTime":"$context.requestTime", "httpMethod":"$context.httpMethod","routeKey":"$context.routeKey", "status":"$context.status","protocol":"$context.protocol", "responseLength":"$context.responseLength" }'

    # Enable REST API logs
    # This can either be set to `restApi: true` to use defaults, or configured via subproperties
    # Can only be configured if the API is created by Serverless Framework
    restApi:
      # Enables HTTP access logs (default: true)
      accessLogging: true
      # Log format to use for access logs
      format: 'requestId: $context.requestId'
      # Enable execution logging (default: true)
      executionLogging: true
      # Log level to use for execution logging: INFO or ERROR
      level: INFO
      # Log full requests/responses for execution logging (default: true)
      fullExecutionData: true
      # Existing IAM role to use for API Gateway when writing CloudWatch Logs (default: automatically created)
      role: arn:aws:iam::123456:role
      # Whether the API Gateway CloudWatch Logs role setting is not managed by Serverless (default: false)
      roleManagedExternally: false

    # Enable Websocket API logs
    # This can either be set to `websocket: true` to use defaults, or configured via subproperties.
    websocket:
      # Enables HTTP access logs (default: true)
      accessLogging: true
      # Log format to use for access logs
      format: 'requestId: $context.requestId'
      # Enable execution logging (default: true)
      executionLogging: true
      # Log level to use for execution logging: INFO or ERROR
      level: INFO
      # Log full requests/responses for execution logging (default: true)
      fullExecutionData: true

    # Optional, whether to write CloudWatch logs for custom resource lambdas as added by the framework
    frameworkLambda: true
```

### S3 buckets

Configure the S3 buckets created for [S3 Lambda events](../events/s3.md):

```yml
provider:
  # If you need to configure the bucket itself, you'll need to add s3 resources to the provider configuration
  s3:
    # Eventual additional properties in camel case
    bucketOne:
      # Supported properties are the same ones as supported by CF resource for S3 bucket
      # See https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-s3-bucket.html
      name: my-custom-bucket-name
      versioningConfiguration:
        Status: Enabled
```

## Package

The `serverless package` or `serverless deploy` commands [package the code of all functions into zip files](./packaging.md).
These zip files are then used for deployments.

```yml
# serverless.yml

# Optional deployment packaging configuration
package:
  # Directories and files to include in the deployed package
  patterns:
    - src/**
    - handler.js
    - '!.git/**'
    - '!.travis.yml'
  # Package each function as an individual artifact (default: false)
  individually: true
  # Explicitly set the package artifact to deploy (overrides native packaging behavior)
  artifact: path/to/my-artifact.zip
  # Automatically exclude NPM dev dependencies from the deployed package (default: true)
  excludeDevDependencies: false
```

## AWS Lambda Functions

Configure the Lambda functions to deploy ([complete documentation](./functions.md)):

```yml
# serverless.yml

functions:
  # A function
  hello:
    # The file and module for this specific function. Cannot be used with 'image'.
    handler: users.create
    # Container image to use. Cannot be used with 'handler'.
    # Can be the URI of an image in ECR, or the name of an image defined in 'provider.ecr.images'
    image: baseimage
    runtime: nodejs14.x
    runtimeManagement:
      mode: manual # syntax required for manual, mode property also supports 'auto' or 'onFunctionUpdate' (see provider.runtimeManagement)
      arn: <aws runtime arn> # required when mode is manual
    # Memory size (default: 1024MB)
    memorySize: 512
    # Timeout (default: 6 seconds)
    # Note: API Gateway has a maximum timeout of 30 seconds
    timeout: 10
    # Function environment variables
    environment:
      APP_ENV_VARIABLE: FOOBAR
    # Configure the size of ephemeral storage available to your Lambda function (in MBs, default: 512)
    ephemeralStorageSize: 512
    # Override the Lambda function name
    name: ${sls:stage}-lambdaName
    description: My function
    # Processor architecture: 'x86_64' or 'arm64' via Graviton2 (default: x86_64)
    architecture: x86_64
    # Reserve a maximum number of concurrent instances (default: account limit)
    reservedConcurrency: 5
    # Provision a minimum number of concurrent instances (default: 0)
    provisionedConcurrency: 3
    # Override the IAM role to use for this function
    role: arn:aws:iam::XXXXXX:role/role
    # SNS topic or SQS ARN to use for the DeadLetterConfig (failed executions)
    onError: arn:aws:sns:us-east-1:XXXXXX:sns-topic
    # KMS key ARN to use for encryption for this function
    kmsKeyArn: arn:aws:kms:us-east-1:XXXXXX:key/some-hash
    # Defines if you want to make use of SnapStart, this feature can only be used in combination with a Java runtime. Configuring this property will result in either None or PublishedVersions for the Lambda function
    snapStart: true
    # Disable the creation of the CloudWatch log group
    disableLogs: false
    # Duration for CloudWatch log retention (default: forever). Overrides provider setting.
    logRetentionInDays: 14
    # Optional Configuration of Lambda Logging Configuration, if this is also set at the provider level, then a given functions configuration will take priority.
    logs:
      # The Log Format to be used for all lambda functions (default: Text)
      logFormat: JSON
      # The Application Log Level to be used, This can only be set if `logFormat` is set to `JSON`
      applicationLogLevel: ERROR
      # The System Log Level to be used, This can only be set if `logFormat` is set to `JSON`
      systemLogLevel: INFO
      # The LogGroup that will be used by default. If this is set the Framework will not create LogGroups for any functions
      logGroup: /aws/lambda/global-log-group
    tags: # Function specific tags
      foo: bar
    # VPC settings for this function
    # If you use VPC then both subproperties (securityGroupIds and subnetIds) are required
    # Can be set to '~' to disable the use of a VPC
    vpc:
      securityGroupIds:
        - securityGroupId1
        - securityGroupId2
      subnetIds:
        - subnetId1
        - subnetId2
    # Lambda URL definition for this function, optional
    # Can be defined as `true` which will create URL without authorizer and cors settings
    url:
      authorizer: 'aws_iam' # Authorizer used for calls to Lambda URL
      cors:  # CORS configuration for Lambda URL, can also be defined as `true` with default CORS configuration
        allowedOrigins:
          - *
        allowedHeaders:
          - Authorization
        allowedMethods:
          - GET
        allowCredentials: true
        exposedResponseHeaders:
          - SomeHeader
        maxAge: 3600
    # Packaging rules specific to this function
    package:
      # Directories and files to include in the deployed package
      patterns:
        - src/**
        - handler.js
        - '!.git/**'
        - '!.travis.yml'
      # Explicitly set the package artifact to deploy (overrides native packaging behavior)
      artifact: path/to/my-artifact.zip
      # Package this function as an individual artifact (default: false)
      individually: true
    # ARN of Lambda layers to use
    layers:
      - arn:aws:lambda:region:XXXXXX:layer:LayerName:Y
    # Overrides the provider setting. Can be 'Active' or 'PassThrough'
    tracing: Active
    # Conditionally deploy the function
    condition: SomeCondition
    # CloudFormation 'DependsOn' option
    dependsOn:
      - MyThing
      - MyOtherThing
    # Lambda destination settings
    destinations:
      # Function name or ARN (or reference) of target (EventBridge/SQS/SNS topic)
      onSuccess: functionName
      # Function name or ARN (or reference) of target (EventBridge/SQS/SNS topic)
      onFailure: arn:xxx:target
      onFailure:
        type: sns
        arn:
          Ref: SomeTopicName
    # Mount an EFS filesystem
    fileSystemConfig:
      # ARN of EFS Access Point
      arn: arn:aws:elasticfilesystem:us-east-1:11111111:access-point/fsap-a1a1a1
      # Path under which EFS will be mounted and accessible in Lambda
      localMountPath: /mnt/example
    # Maximum retry attempts when an asynchronous invocation fails (between 0 and 2; default: 2)
    maximumRetryAttempts: 1
    # Maximum event age in seconds when invoking asynchronously (between 60 and 21600)
    maximumEventAge: 7200
```

## AWS Lambda Events

Reference of [Lambda events](./events.md) that trigger functions:

### API Gateway v2 HTTP API

[API Gateway v2 HTTP API events](../events/http-api.md):

```yaml
functions:
  hello:
    # ...
    events:
      # HTTP API endpoint (API Gateway v2)
      - httpApi:
          method: GET
          path: /some-get-path/{param}
          authorizer: # Optional
            # Name of an authorizer defined in 'provider.httpApi.authorizers'
            name: someJwtAuthorizer
            scopes: # Optional
              - user.id
              - user.email
```

### API Gateway v1 REST API

[API Gateway v1 REST API events](../events/apigateway.md):

```yaml
functions:
  hello:
    # ...
    events:
      # REST API endpoint (API Gateway v1)
      - http:
          # Path for this endpoint
          path: users/create
          # HTTP method for this endpoint
          method: get
          # Enable CORS. Don't forget to return the right header in your response
          cors: true
          # Requires clients to add API keys values in the `x-api-key` header of their request
          private: true
          # An AWS API Gateway custom authorizer function
          authorizer:
            # Name of the authorizer function (must be in this service)
            name: authorizerFunc
            # Can be used instead of a name to reference a function outside of service
            arn: xxx:xxx:Lambda-Name
            resultTtlInSeconds: 0
            identitySource: method.request.header.Authorization
            identityValidationExpression: someRegex
            # Input of the authorizer function: auth token ('token') or the entire request event ('request') (default: token)
            type: token
          # Configure method request and integration request settings
          request:
            # HTTP endpoint URL and map path parameters for HTTP and HTTP_PROXY requests
            uri: http://url/{paramName}
            # Optional request parameter configuration
            parameters:
              paths:
                paramName: true # mark path parameter as required
              headers:
                headerName: true # mark header as required
                custom-header:
                  required: true
                  # Map the header to a static value or integration request variable
                  mappedValue: context.requestId
              querystrings:
                paramName: true # mark query string
            # Request schema validation mapped by content type
            schemas:
              # Define the valid JSON Schema for this content-type
              application/json: ${file(create_request.json)}
              application/json+abc:
                # Name of the API Gateway model
                name: ModelName
                description: 'Some description'
                schema: ${file(model_schema.json)}
            # Custom request mapping templates that overwrite default templates
            template:
              application/json: '{ "httpMethod" : "$context.httpMethod" }'
            # Optional define pass through behavior when content-type does not match any of the specified mapping templates
            passThrough: NEVER
```

### Websocket API

[API Gateway websocket events](../events/websocket.md):

```yaml
functions:
  hello:
    # ...
    events:
      - websocket:
          route: $connect
          # Optional, setting this enables callbacks on websocket requests for two-way communication
          routeResponseSelectionExpression: $default
          authorizer:
            # Use either "name" or arn" properties
            name: auth
            arn: arn:aws:lambda:us-east-1:1234567890:function:auth
            identitySource:
              - 'route.request.header.Auth'
              - 'route.request.querystring.Auth'
```

### S3

[S3 events](../events/s3.md):

```yaml
functions:
  hello:
    # ...
    events:
      - s3:
          bucket: photos
          event: s3:ObjectCreated:*
          rules:
            - prefix: uploads/
            - suffix: .jpg
          # Set to 'true' when using an existing bucket
          # Else the bucket will be automatically created
          existing: true
          # Optional, for forcing deployment of triggers on existing S3 buckets
          forceDeploy: true
```

### Schedule

[Schedule events](../events/schedule.md):

```yaml
functions:
  hello:
    # ...
    events:
      - schedule:
          name: my scheduled event
          description: a description of my scheduled event's purpose
          # Can also be an array of rate/cron expressions
          rate: rate(10 minutes)
          # (default: true)
          enabled: false
          # Note, you can use only one of input, inputPath, or inputTransformer
          input:
            key1: value1
            key2: value2
            stageParams:
              stage: dev
          inputPath: '$.stageVariables'
          inputTransformer:
            inputPathsMap:
              eventTime: '$.time'
            inputTemplate: '{"time": <eventTime>, "key1": "value1"}'
```

### SNS

[SNS events](../events/sns.md):

```yaml
functions:
  hello:
    # ...
    events:
      - sns:
          topicName: aggregate
          displayName: Data aggregation pipeline
          filterPolicy:
            pet:
              - dog
              - cat
          filterPolicyScope: MessageAttributes
          redrivePolicy:
            # (1) ARN
            deadLetterTargetArn: arn:aws:sqs:us-east-1:11111111111:myDLQ
            # (2) Ref (resource defined in same CF stack)
            deadLetterTargetRef: myDLQ
            # (3) Import (resource defined in outer CF stack)
            deadLetterTargetImport:
              arn: MyShared-DLQArn
              url: MyShared-DLQUrl
```

### SQS

[SQS events](../events/sqs.md):

```yaml
functions:
  hello:
    # ...
    events:
      - sqs:
          arn: arn:aws:sqs:region:XXXXXX:myQueue
          # Optional
          batchSize: 10
          # Optional, minimum is 0 and the maximum is 300 (seconds)
          maximumBatchingWindow: 10
          # (default: true)
          enabled: false
          functionResponseType: ReportBatchItemFailures
          filterPatterns:
            - a: [1, 2]
```

### Streams

[Stream events](../events/streams.md):

```yaml
functions:
  hello:
    # ...
    events:
      - stream:
          arn: arn:aws:kinesis:region:XXXXXX:stream/foo
          batchSize: 100
          maximumRecordAgeInSeconds: 120
          startingPosition: LATEST
          # (default: true)
          enabled: false
          functionResponseType: ReportBatchItemFailures
          filterPatterns:
            - partitionKey: [1]
```

### MSK

[MSK events](../events/msk.md):

```yaml
functions:
  hello:
    # ...
    events:
      - msk:
          # ARN of MSK Cluster
          arn: arn:aws:kafka:us-east-1:111111111:cluster/ClusterName/a1a1a1a1a
          # name of Kafka topic to consume from
          topic: kafkaTopic
          # Optional, must be in 1-10000 range
          batchSize: 100
          # Optional, must be in 0-300 range (seconds)
          maximumBatchingWindow: 30
          # Optional, can be set to LATEST, AT_TIMESTAMP or TRIM_HORIZON
          startingPosition: LATEST
          # Mandatory when startingPosition is AT_TIMESTAMP, must be in Unix time seconds
          startingPositionTimestamp: 10000123
          # (default: true)
          enabled: false
          # Optional, arn of the secret key for authenticating with the brokers in your MSK cluster.
          saslScram512: arn:aws:secretsmanager:region:XXXXXX:secret:AmazonMSK_xxxxxx
          # Optional, specifies the consumer group ID to be used when consuming from Kafka. If not provided, a random UUID will be generated
          consumerGroupId: MyConsumerGroupId
          # Optional, specifies event pattern content filtering
          filterPatterns:
            - value:
                a: [1, 2]
```

### ActiveMQ

[ActiveMQ events](../events/activemq.md):

```yaml
functions:
  hello:
    # ...
    events:
      - activemq:
          # ARN of ActiveMQ Broker
          arn: arn:aws:mq:us-east-1:0000:broker:ExampleMQBroker:b-xxx-xxx
          # Name of ActiveMQ queue consume from
          queue: queue-name
          # Secrets Manager ARN for basic auth credentials
          basicAuthArn: arn:aws:secretsmanager:us-east-1:01234567890:secret:MySecret
          # Optional, must be in 1-10000 range
          batchSize: 100
          # Optional, must be in 0-300 range (seconds)
          maximumBatchingWindow: 30
          # Optional, can be set to LATEST or TRIM_HORIZON
          startingPosition: LATEST
          # (default: true)
          enabled: false
          # Optional, specifies event pattern content filtering
          filterPatterns:
            - value:
                a: [1, 2]
```

### Kafka

[Kakfa events](../events/kafka.md):

```yaml
functions:
  hello:
    # ...
    events:
      - kafka:
          # See main kafka documentation for various access configuration settings
          accessConfigurations:
            # ...
          # An array of bootstrap server addresses
          bootstrapServers:
            - abc3.xyz.com:9092
            - abc2.xyz.com:9092
          # name of Kafka topic to consume from
          topic: MySelfManagedKafkaTopic
          # Optional, must be in 1-10000 range
          batchSize: 100
          # Optional, must be in 0-300 range (seconds)
          maximumBatchingWindow: 30
          # Optional, can be set to LATEST, AT_TIMESTAMP or TRIM_HORIZON
          startingPosition: LATEST
          # Mandatory when startingPosition is AT_TIMESTAMP
          startingPositionTimestamp: 10000123
          # (default: true)
          enabled: false
          # Optional, specifies the consumer group ID to be used when consuming from Kafka. If not provided, a random UUID will be generated
          consumerGroupId: MyConsumerGroupId
          # Optional, specifies event pattern content filtering
          filterPatterns:
            - eventName: INSERT
```

### RabbitMQ

[RabbitMQ events](../events/rabbitmq.md):

```yaml
functions:
  hello:
    # ...
    events:
      - rabbitmq:
          # ARN of RabbitMQ Broker
          arn: arn:aws:mq:us-east-1:0000:broker:ExampleMQBroker:b-xxx-xxx
          # Name of RabbitMQ queue consume from
          queue: queue-name
          # Name of RabbitMQ virtual host to consume from
          virtualHost: virtual-host
          # Secrets Manager ARN for basic auth credentials
          basicAuthArn: arn:aws:secretsmanager:us-east-1:01234567890:secret:MySecret
          # Optional, must be in 1-10000 range
          batchSize: 100
          # Optional, must be in 0-300 range (seconds)
          maximumBatchingWindow: 30
          # Optional, can be set to LATEST or TRIM_HORIZON
          startingPosition: LATEST
          # (default: true)
          enabled: false
          # Optional, specifies event pattern content filtering
          filterPatterns:
            - value:
                a: [1, 2]
```

### Alexa

[Alexa Skill events](../events/alexa-skill.md) and [Alexa Smart Home events](../events/alexa-smart-home.md):

```yaml
functions:
  hello:
    # ...
    events:
      - alexaSkill:
          appId: amzn1.ask.skill.xx-xx-xx-xx
          # (default: true)
          enabled: false
      - alexaSmartHome:
          appId: amzn1.ask.skill.xx-xx-xx-xx
          # (default: true)
          enabled: false
```

### IOT

[IoT events](../events/iot.md):

```yaml
functions:
  hello:
    # ...
    events:
      - iot:
          name: myIoTEvent
          description: An IoT event
          sql: "SELECT * FROM 'some_topic'"
          sqlVersion: beta
          # (default: true)
          enabled: false
```

### CloudWatch

[CloudWatch events](../events/cloudwatch-event.md) and [CloudWatch logs events](../events/cloudwatch-log.md):

```yaml
functions:
  hello:
    # ...
    events:
      - cloudwatchEvent:
          event:
            source:
              - 'aws.ec2'
            detail-type:
              - 'EC2 Instance State-change Notification'
            detail:
              state:
                - pending
          # Note, you can use only one of input, inputPath, or inputTransformer
          input:
            key1: value1
            key2: value2
            stageParams:
              stage: dev
          inputPath: '$.stageVariables'
          inputTransformer:
            inputPathsMap:
              eventTime: '$.time'
            inputTemplate: '{"time": <eventTime>, "key1": "value1"}'
      - cloudwatchLog:
          logGroup: '/aws/lambda/hello'
          filter: '{$.userIdentity.type = Root}'
```

### Cognito

[Cognito User Pool events](../events/cognito-user-pool.md):

```yaml
functions:
  hello:
    # ...
    events:
      - cognitoUserPool:
          pool: MyUserPool
          trigger: PreSignUp
          # Optional, if you're referencing an existing User Pool
          existing: true
          # Optional, for forcing deployment of triggers on existing User Pools
          forceDeploy: true
      - cognitoUserPool:
          pool: MyUserPool
          trigger: CustomEmailSender
          # Required, if you're using the CustomSMSSender or CustomEmailSender triggers
          # Can either be KMS Key ARN string or reference to KMS Key Resource ARN
          kmsKeyId: 'arn:aws:kms:eu-west-1:111111111111:key/12345678-9abc-def0-1234-56789abcdef1'
          existing: true
          forceDeploy: true
```

### ALB

[Application Load Balancer events](../events/alb.md):

```yaml
functions:
  hello:
    # ...
    events:
      - alb:
          listenerArn: arn:aws:elasticloadbalancing:us-east-1:12345:listener/app/my-load-balancer/50dcc0c9188/
          priority: 1
          targetGroupName: helloTargetGroup # optional
          conditions:
            host: example.com
            path: /hello
          # Optional, can also be set using a boolean value
          healthCheck:
            path: / # optional
            intervalSeconds: 35 # optional
            timeoutSeconds: 30 # optional
            healthyThresholdCount: 5 # optional
            unhealthyThresholdCount: 5 # optional
            matcher: # optional
              httpCode: '200'
```

### EventBridge

[EventBridge events](../events/event-bridge.md):

```yaml
functions:
  hello:
    # ...
    events:
      # Use the default AWS event bus
      - eventBridge:
          description: a description of my eventBridge event's purpose
          schedule: rate(10 minutes)
      # Create a custom event bus
      - eventBridge:
          eventBus: custom-saas-events
          pattern:
            source:
              - saas.external
      # Re-use an existing event bus
      - eventBridge:
          eventBus: arn:aws:events:us-east-1:12345:event-bus/custom-private-events
          pattern:
            source:
              - custom.private
          inputTransformer:
            inputPathsMap:
              eventTime: '$.time'
            inputTemplate: '{"time": <eventTime>, "key1": "value1"}'
      # Using 'inputs'
      - eventBridge:
          pattern:
            source:
              - 'aws.ec2'
            detail-type:
              - 'EC2 Instance State-change Notification'
            detail:
              state:
                - pending
          input:
            key1: value1
            key2: value2
            stageParams:
              stage: dev
      # Using 'inputPath'
      - eventBridge:
          pattern:
            source:
              - 'aws.ec2'
            detail-type:
              - 'EC2 Instance State-change Notification'
            detail:
              state:
                - pending
          inputPath: '$.stageVariables'
      # Using 'inputTransformer'
      - eventBridge:
          pattern:
            source:
              - 'aws.ec2'
            detail-type:
              - 'EC2 Instance State-change Notification'
            detail:
              state:
                - pending
          inputTransformer:
            inputPathsMap:
              eventTime: '$.time'
            inputTemplate: '{"time": <eventTime>, "key1": "value1"}'
          retryPolicy:
            maximumEventAge: 3600
            maximumRetryAttempts: 3
          deadLetterQueueArn: !GetAtt QueueName.Arn
```

### CloudFront

[CloudFront Lambda@Edge events](../events/cloudfront.md):

```yaml
functions:
  hello:
    # ...
    events:
      - cloudFront:
          eventType: viewer-response
          includeBody: true
          pathPattern: /docs*
          cachePolicy:
            # Use either name or id
            # Refers to a Cache Policy defined in 'provider.cloudFront.cachePolicies'
            name: myCachePolicy1
            # Refers to any external Cache Policy ID
            id: 658327ea-f89d-4fab-a63d-7e88639e58f6
          origin:
            DomainName: serverless.com
            OriginPath: /framework
            CustomOriginConfig:
              OriginProtocolPolicy: match-viewer
```

## Function layers

Deploy [Lambda function layers](./layers.md):

```yml
# serverless.yml

layers:
  # A Lambda layer
  hello:
    # required, path to layer contents on disk
    path: layer-dir
    # optional, Deployed Lambda layer name
    name: ${sls:stage}-layerName
    # optional, Description to publish to AWS
    description: Description of what the lambda layer does
    # optional, a list of runtimes this layer is compatible with
    compatibleRuntimes:
      - python3.11
    # optional, a list of architectures this layer is compatible with
    compatibleArchitectures:
      - x86_64
      - arm64
    # optional, a string specifying license information
    licenseInfo: GPLv3
    # optional, a list of AWS account IDs allowed to access this layer.
    allowedAccounts:
      - '*'
    # optional, false by default. If true, layer versions are not deleted as new ones are created
    retain: false
```

## AWS Resources

[Customize the CloudFormation template](./services.md#serverlessyml), for example to deploy extra CloudFormation resource:

```yml
# serverless.yml

# Insert raw CloudFormation (resources, outputs…) in the deployed template
resources:
  Resources:
    usersTable:
      Type: AWS::DynamoDB::Table
      Properties:
        TableName: usersTable
        AttributeDefinitions:
          - AttributeName: email
            AttributeType: S
        KeySchema:
          - AttributeName: email
            KeyType: HASH
        ProvisionedThroughput:
          ReadCapacityUnits: 1
          WriteCapacityUnits: 1

  extensions:
    # override Properties or other attributes of Framework-created resources.
    # See https://serverless.com/framework/docs/providers/aws/guide/resources#override-aws-cloudformation-resource for more details
    UsersCreateLogGroup:
      Properties:
        RetentionInDays: '30'

  # The "Outputs" that your AWS CloudFormation Stack should produce.  This allows references between services.
  Outputs:
    UsersTableArn:
      Description: The ARN for the User's Table
      Value: !GetAtt usersTable.Arn
      Export:
        # see Fn::ImportValue to use in other services
        # and http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/outputs-section-structure.html for documentation on use.
        Name: ${self:service}:${sls:stage}:UsersTableArn
```