Serverless Framework: serverless.yml Config & Validation Guide

The Serverless Framework turns AWS Lambda deployment into a single YAML file and one CLI command. This reference covers every section of serverless.yml, common patterns, plugin setup, and how to choose between Serverless Framework, SAM, and CDK.

The serverless.yml Structure

A complete serverless.yml has six top-level sections:

# serverless.yml — complete reference
service: my-api-service

frameworkVersion: '3'

provider:
  name: aws
  runtime: nodejs20.x
  region: us-east-1
  stage: ${opt:stage, 'dev'}
  memorySize: 512
  timeout: 30
  environment:
    NODE_ENV: ${self:provider.stage}
    DB_URL: ${ssm:/myapp/${self:provider.stage}/db-url}
  iam:
    role:
      statements:
        - Effect: Allow
          Action:
            - dynamodb:Query
            - dynamodb:PutItem
          Resource: !GetAtt UsersTable.Arn

plugins:
  - serverless-webpack
  - serverless-offline
  - serverless-prune-plugin

custom:
  webpack:
    webpackConfig: webpack.config.js
    includeModules: false
  prune:
    automatic: true
    number: 3

functions:
  api:
    handler: src/api.handler
    events:
      - httpApi:
          path: /users
          method: GET
      - httpApi:
          path: /users/{id}
          method: GET
  processor:
    handler: src/processor.handler
    events:
      - sqs:
          arn: !GetAtt ProcessingQueue.Arn
          batchSize: 10

resources:
  Resources:
    UsersTable:
      Type: AWS::DynamoDB::Table
      Properties:
        TableName: users-${self:provider.stage}
        BillingMode: PAY_PER_REQUEST
        AttributeDefinitions:
          - AttributeName: id
            AttributeType: S
        KeySchema:
          - AttributeName: id
            KeyType: HASH

Custom Variables and Stage Configuration

Use the custom section to define stage-specific settings that functions and resources reference:

custom:
  settings:
    dev:
      domainName: dev-api.example.com
      logLevel: DEBUG
      reservedConcurrency: 5
    production:
      domainName: api.example.com
      logLevel: WARN
      reservedConcurrency: 100

  # Reference: ${self:custom.settings.${self:provider.stage}.logLevel}

functions:
  api:
    handler: src/handler.ts
    reservedConcurrency: ${self:custom.settings.${self:provider.stage}.reservedConcurrency}
    environment:
      LOG_LEVEL: ${self:custom.settings.${self:provider.stage}.logLevel}

Deploying with the Serverless Framework CLI

# Install
npm install -g serverless

# Deploy to dev (default stage)
serverless deploy

# Deploy to production
serverless deploy --stage production --region us-east-1

# Deploy a single function only (faster)
serverless deploy function --function api --stage production

# Remove all resources
serverless remove --stage production

# Invoke a function directly
serverless invoke --function api --stage dev --data '{"httpMethod":"GET"}'

# View logs
serverless logs --function api --stage production --tail

Serverless Framework vs SAM vs CDK Comparison