AWS Infrastructure Resources

OSS Serverless deploys using the AWS CloudFormation engine under the hood. If you want to deploy AWS resources that are not natively supported by serverless.yml (like AWS DynamoDB or AWS S3), you can deploy anything via the resources section.

Configuration

Every stage you deploy with serverless.yml is a single AWS CloudFormation stack. This is where your AWS Lambda functions and their event configurations are defined and it’s how they are deployed. When you add resources to serverless.yml, those resources are added into your CloudFormation stack upon serverless deploy.

Define your AWS resources in a property titled resources. What goes in this property is raw CloudFormation template syntax, in YAML, like this:

service: usersCrud
provider: aws
functions:

resources: # CloudFormation template syntax
  Resources:
    usersTable:
      Type: AWS::DynamoDB::Table
      Properties:
        TableName: usersTable
        AttributeDefinitions:
          - AttributeName: email
            AttributeType: S
        KeySchema:
          - AttributeName: email
            KeyType: HASH
        ProvisionedThroughput:
          ReadCapacityUnits: 1
          WriteCapacityUnits: 1

You can attach any kind of resource to your CloudFormation stack. You can add Resources, Outputs. You can also use variables for sensitive data or reusable configuration in your resources templates.

Note: By supplying your resources at resources.Resources you may accidentally override resources as generated by the framework. To intentionally extend such resources, please use resources.extensions, see Override AWS CloudFormation Resource section for more info.

Note: You can now remove resource properties with null assignment. Since CloudFormation does not allow this, Serverless will strip these properties from the final template before upload.

AWS CloudFormation Resource Reference

To have consistent naming in the CloudFormation Templates that get deployed we use a standard pattern:

{Function Name}{Cloud Formation Resource Type}{Resource Name}{SequentialID, instanceId or Random String}

Function Name - This is optional for Resources that should be recreated when the function name gets changed. Those resources are also called function bound
Cloud Formation Resource Type - E.g., S3Bucket
Resource Name - An identifier for the specific resource, e.g. for an S3 Bucket the configured bucket name.
SequentialID, instanceId or Random String - For a few resources we need to add an optional sequential id, the Serverless instanceId (accessible via ${sls:instanceId}) or a random string to identify them

All resource names that are deployed by Serverless have to follow this naming scheme. The only exception (for backwards compatibility reasons) is the S3 Bucket that is used to upload artifacts so they can be deployed to your function.

We’re also using the term normalizedName or similar terms in this guide. This means dropping any characters that aren’t allowed in resources names, e.g. special characters.

If you have path variables in your url, they get normalized too, and there is a Var added implicitly. So normalizedPath for POST /users/{user_id} will be normalized to UsersUseridVarTestPost

Tip: If you are unsure how a resource is named, that you want to reference from your custom resources, you can issue a serverless package. This will create the CloudFormation template for your service in the .serverless folder (it is named cloudformation-template-update-stack.json). Just open the file and check for the generated resource name.

AWS Resource	Name Template	Example
S3::Bucket	S3Bucket{normalizedBucketName}	S3BucketMybucket
IAM::Role	IamRoleLambdaExecution	IamRoleLambdaExecution
Lambda::Function	{normalizedFunctionName}LambdaFunction	HelloLambdaFunction
Lambda::Url	{normalizedFunctionName}LambdaFunctionUrl	HelloLambdaFunctionUrl
Lambda::Version	{normalizedFunctionName}LambdaVersion{sha256}	HelloLambdaVersionr3pgoTvv1xT4E4NiCL6JG02fl6vIyi7OS1aW0FwAI
Logs::LogGroup	{normalizedFunctionName}LogGroup	HelloLogGroup
Lambda::Permission	Schedule: {normalizedFunctionName}LambdaPermissionEventsRuleSchedule{index} CloudWatch Event: {normalizedFunctionName}LambdaPermissionEventsRuleCloudWatchEvent{index} CloudWatch Log: {normalizedFunctionName}LambdaPermissionLogsSubscriptionFilterCloudWatchLog{index} IoT: {normalizedFunctionName}LambdaPermissionIotTopicRule{index} S3: {normalizedFunctionName}LambdaPermission{normalizedBucketName}S3 APIG: {normalizedFunctionName}LambdaPermissionApiGateway SNS: {normalizedFunctionName}LambdaPermission{normalizedTopicName}SNS Alexa Skill: {normalizedFunctionName}LambdaPermissionAlexaSkill Alexa Smart Home: {normalizedFunctionName}LambdaPermissionAlexaSmartHome{index} Cognito User Pool Trigger Source: {normalizedFunctionName}LambdaPermissionCognitoUserPool{normalizedPoolId}TriggerSource{triggerSource}	Schedule: HelloLambdaPermissionEventsRuleSchedule1 CloudWatch Event: HelloLambdaPermissionEventsRuleCloudWatchEvent1 CloudWatch Log: HelloLambdaPermissionLogsSubscriptionFilterCloudWatchLog1 IoT: HelloLambdaPermissionIotTopicRule1 S3: HelloLambdaPermissionBucketS3 APIG: HelloLambdaPermissionApiGateway SNS: HelloLambdaPermissionTopicSNS Alexa Skill: HelloLambdaPermissionAlexaSkill Alexa Smart Home: HelloLambdaPermissionAlexaSmartHome1 Cognito User Pool Trigger Source: HelloLambdaPermissionCognitoUserPoolMyPoolTriggerSourceCustomMessage
Events::Rule	Schedule: {normalizedFunctionName}EventsRuleSchedule{SequentialID} CloudWatch Event: {normalizedFunctionName}EventsRuleCloudWatchEvent{SequentialID}	Schedule: HelloEventsRuleSchedule1 CloudWatch Event: HelloEventsRuleCloudWatchEvent1
AWS::Logs::SubscriptionFilter	{normalizedFunctionName}LogsSubscriptionFilterCloudWatchLog{SequentialID}	HelloLogsSubscriptionFilterCloudWatchLog1
AWS::IoT::TopicRule	{normalizedFunctionName}IotTopicRule{SequentialID}	HelloIotTopicRule1
ApiGateway::RestApi	ApiGatewayRestApi	ApiGatewayRestApi
ApiGateway::Resource	ApiGatewayResource{normalizedPath}	ApiGatewayResourceUsers
ApiGateway::Method	ApiGatewayMethod{normalizedPath}{normalizedMethod}	ApiGatewayMethodUsersGet
ApiGateway::Authorizer	{normalizedFunctionName}ApiGatewayAuthorizer	HelloApiGatewayAuthorizer
ApiGateway::Deployment	ApiGatewayDeployment{instanceId}	ApiGatewayDeployment12356789
ApiGateway::ApiKey	ApiGatewayApiKey{OptionalNormalizedName}{SequentialID}	ApiGatewayApiKeyFree1
ApiGateway::UsagePlan	ApiGatewayUsagePlan{OptionalNormalizedName}	ApiGatewayUsagePlanFree
ApiGateway::UsagePlanKey	ApiGatewayUsagePlanKey{OptionalNormalizedName}{SequentialID}	ApiGatewayUsagePlanKeyFree1
ApiGateway::Stage	ApiGatewayStage	ApiGatewayStage
SNS::Topic	SNSTopic{normalizedTopicName}	SNSTopicSometopic
SNS::Subscription	{normalizedFunctionName}SnsSubscription{normalizedTopicName}	HelloSnsSubscriptionSomeTopic
AWS::Lambda::EventSourceMapping	DynamoDB: {normalizedFunctionName}EventSourceMappingDynamodb{tableName} Kinesis: {normalizedFunctionName}EventSourceMappingKinesis{streamName}	DynamoDB: HelloLambdaEventSourceMappingDynamodbUsers Kinesis: HelloLambdaEventSourceMappingKinesisMystream
Cognito::UserPool	CognitoUserPool{normalizedPoolId}	CognitoUserPoolPoolId

Override AWS CloudFormation Resource

You can override the specific CloudFormation resource to apply your own options (place all such extensions at resources.extensions section). For example, if you want to set AWS::Logs::LogGroup retention time to 30 days, override it with above table’s Name Template.

When you override basic resources, there are two things to keep in mind when it comes to normalizedFunctionName:

It should start with an uppercase character
The - will be changed to Dash, _ will be changed to Underscore

Here’s an example:

functions:
  write-post:
    handler: handler.writePost
    events:
      - httpApi: 'POST /api/posts/new'

resources:
  extensions:
    WriteDashPostLogGroup:
      Properties:
        RetentionInDays: '30'

Here’s how the extension logic is defined:

Resource attribute	Operation
`Condition`	Set to extension value if present.
`CreationPolicy`	Set to extension value if present.
`DeletionPolicy`	Set to extension value if present.
`DependsOn`	Merge. The extension value will be added to the resource’s `DependsOn` list.
`Metadata`	Merge. If a metadata key with the same name exists in the resource, the value will be replaced with the extension value.
`Properties`	Merge. If a property with the same name exists in the resource, the value will be replaced with the extension value.
`UpdatePolicy`	Set to extension value if present.
`UpdateReplacePolicy`	Set to extension value if present.
other	Not supported. An error will be thrown if you try to extend an unsupported attribute.

Extending using resources.extensions only works on the Resources part of the CloudFormation template.