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}/*'