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 in the official Serverless documentation.

Overview

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 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 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.

You can find the list of all Serverless plugins here.

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
• faster cold starts

Read more about the package configuration in the serverless.yml documentation.

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.

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:

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 and then use the iamRoleStatements at the function definition block.

Resources

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

The resources section contains raw CloudFormation syntax. This lets us define any kind of AWS resource other than Lambda functions.

Read more in the Serverless documentation about resources.

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

resources:
    Resources:
        # ...

References

The CloudFormation !Ref syntax can be used. However the ${MyResource.Arn} CloudFormation syntax cannot be used.

To solve this, the serverless-pseudo-parameters plugin can help. After installing it, you can reference other resources by replacing the ${...} syntax with #{...} (because ${...} is conflicting with serverless.yml native variables).

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

#...

plugins:
    - serverless-pseudo-parameters

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: '#{MyBucket.Arn}/*'