serverless.yml

Your application is deployed using the Serverless framework based on the serverless.yml configuration file.

This page introduces a few advanced concepts of the serverless.yml format. You can learn more in the official Serverless documentation (opens in a new tab).

Overview

serverless.yml

service: app
 
provider:
    name: aws
 
plugins:
    - ./vendor/bref/bref
 
functions:
    foo:
        handler: index.php
        runtime: php-81
 
resources:
    Resources:
        MyBucket:
            Type: AWS::S3::Bucket
            Properties:
                BucketName: 'my-bucket'

Service

service: app

The service (opens in a new tab) is simply the name of your project.

Since Serverless lets us deploy a project in multiple stages (prod, dev, staging…), CloudFormation stacks will contain both the service name and the stage: app-prod, app-dev, etc.

Provider

provider:
    name: aws

Bref only supports the aws provider, even though Serverless can deploy applications on other cloud providers like Google Cloud, Azure, etc.

provider:
    name: aws
    # The AWS region in which to deploy (us-east-1 by default)
    region: us-east-1
    # The stage of the application, e.g. dev, prod, staging… ('dev' by default)
    stage: dev

The provider section also lets us configure global options on all functions:

provider:
    name: aws
    runtime: php-81
    timeout: 10
 
functions:
    foo:
        handler: foo.php
    bar:
        handler: bar.php
 
# ...

is the same as:

provider:
    name: aws
 
functions:
    foo:
        handler: foo.php
        runtime: php-81
        timeout: 10
    bar:
        handler: bar.php
        runtime: php-81
        timeout: 10
 
# ...

Plugins

plugins:
    - ./vendor/bref/bref

Serverless plugins (opens in a new tab) are JavaScript plugins that extend the behavior of the Serverless framework.

Bref provides a plugin via the Composer package, which explains why the path is a relative path into the vendor directory. This plugin provides support for the Bref runtimes and layers, it is necessary to include it.

Most other Serverless plugins are installed via npm (opens in a new tab).

You can find the list of all Serverless plugins here (opens in a new tab).

Exclusions

It is possible to exclude directories from being deployed via the package.patterns section:

package:
    patterns:
        - '!node_modules/**'
        - '!tests/**'

This has the following benefits:

faster deployments
less risk of hitting Lambda's size limit (opens in a new tab)
faster cold starts

Read more about the package configuration in the serverless.yml documentation (opens in a new tab).

Functions

functions:
    foo:
        handler: foo.php
        runtime: php-81
    bar:
        handler: bar.php
        runtime: php-81

Functions are AWS Lambda functions. You can find all options available in this Serverless documentation page (opens in a new tab).

Note that it is possible to mix PHP functions with functions written in other languages in the same serverless.yml config.

Permissions

If your lambda needs to access other AWS services (S3, SQS, SNS…), you will need to add the proper permissions via the iam.role.statements section (opens in a new tab):

provider:
    name: aws
    timeout: 10
    runtime: provided.al2
    iam:
        role:
            statements:
                # Allow to put a file in the `my-bucket` S3 bucket
                -   Effect: Allow
                    Action: s3:PutObject
                    Resource: 'arn:aws:s3:::my-bucket/*'
                # Allow to query and update the `example` DynamoDB table
                -   Effect: Allow
                    Action:
                        - dynamodb:Query
                        - dynamodb:Scan
                        - dynamodb:GetItem
                        - dynamodb:PutItem
                        - dynamodb:UpdateItem
                        - dynamodb:DeleteItem
                    Resource: 'arn:aws:dynamodb:us-east-1:111110002222:table/example'

If you only want to define some permissions per function, instead of globally (ie: in the provider), you should install and enable the Serverless plugin serverless-iam-roles-per-function (opens in a new tab) and then use the iamRoleStatements at the function definition block.

Stage parameters

Stage parameters are a great way to define values that change depending on the stage (dev, prod, staging…).

params:
    # Default parameters that apply to all stages
    default:
        # Here we use the special `sls:stage` variable
        # to define a domain that changes depending on the stage
        domain: ${sls:stage}.preview.myapp.com
    # Parameters that apply to the prod stage
    prod:
        domain: myapp.com
    # Parameters that apply to the dev stage
    dev:
        domain: preview.myapp.com
 
# Parameters can be used via the ${param:XXX} variables:
provider:
    environment:
        APP_DOMAIN: ${param:domain}

Read the full Serverless documentation about stage parameters (opens in a new tab).

Resources

resources:
    Resources:
        MyBucket:
            Type: AWS::S3::Bucket
            Properties:
                BucketName: 'my-bucket'

The resources section contains raw CloudFormation syntax (opens in a new tab). This lets us define any kind of AWS resource other than Lambda functions.

Be careful, the CloudFormation resources must be defined in the resources.Resources sub-section:

resources:
    Resources:
        # ...

CloudFormation functions

The CloudFormation !Ref, !GetAtt and !Sub functions can be used.

Here is an example where we define a S3 bucket and a policy that references it. It uses both the !Ref MyBucket and !Sub '${MyBucket.Arn}' syntaxes:

serverless.yml

#...
 
resources:
    Resources:
        MyBucket:
            Type: AWS::S3::Bucket
        # IAM policy that makes the bucket publicly readable
        MyBucketPolicy:
            Type: AWS::S3::BucketPolicy
            Properties:
                Bucket: !Ref MyBucket
                PolicyDocument:
                    Statement:
                        -   Effect: Allow
                            Principal: '*' # everyone
                            Action: s3:GetObject
                            Resource: !Sub '${MyBucket.Arn}/*'

Custom architecture Environment variables