AWS Lambda

Deploy serverless functions to AWS Lambda using the AWS Serverless Application Model (SAM).

Prerequisites

1. AWS CLI installed and configured
2. AWS SAM CLI installed
3. AWS credentials with Lambda permissions

# Install AWS CLI
brew install awscli

# Install SAM CLI
brew install aws-sam-cli

# Configure credentials
aws configure

Service Configuration

name: my-function
type: aws-lambda
provider: aws
region: us-east-1
project: my-company

build:
  language: go
  version: "1.23"

The CloudFormation stack is named after the service (my-function above).

Required Fields

Field	Description
name	Function name
region	AWS region (e.g., us-east-1)
project	Project name

Function Configuration

Memory, timeout, runtime, and handler are not Pilum fields — they belong in your SAM template.yaml (see below), which is the single source of truth for function configuration. Pilum drives the build and deploy; SAM owns the function.

SAM Template

Pilum works with your existing SAM template. Create template.yaml:

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31

Globals:
  Function:
    Timeout: 30
    MemorySize: 128

Resources:
  MyFunction:
    Type: AWS::Serverless::Function
    Properties:
      FunctionName: my-function
      Handler: bootstrap
      Runtime: provided.al2
      CodeUri: ./dist/
      Architectures:
        - x86_64
      Events:
        Api:
          Type: Api
          Properties:
            Path: /
            Method: ANY

Deployment Steps

The AWS Lambda recipe executes exactly two commands (verify anytime with --dry-run):

1. build — sam build
2. deploy —

   sam deploy --stack-name <service-name> --region <region> \
     --resolve-s3 --capabilities CAPABILITY_IAM \
     --no-confirm-changeset --no-fail-on-empty-changeset --no-progressbar \
     --tags pilum:service=<service-name> pilum:version=<tag>

There is no separate package step: sam deploy --resolve-s3 uploads build artifacts to SAM’s managed S3 bucket itself. --no-fail-on-empty-changeset makes redeploying an unchanged service a success rather than an error, and the stack is tagged with the Pilum service name and version for traceability.

Example Commands

# Deploy Lambda function
pilum deploy --tag=v1.0.0

# Build only
pilum build --tag=v1.0.0

# Preview commands
pilum dry-run --tag=v1.0.0

Environment Variables

Caution

Unlike the Cloud Run recipes, the Lambda recipe does not apply env_vars: or secrets: from pilum.yaml — those fields are ignored for aws-lambda services. Your SAM template.yaml is the single source of truth for function environment and secrets.

Set Lambda environment variables in your SAM template:

Resources:
  MyFunction:
    Type: AWS::Serverless::Function
    Properties:
      Environment:
        Variables:
          LOG_LEVEL: info
          TABLE_NAME: !Ref MyTable

Secrets

Use AWS Secrets Manager:

Resources:
  MyFunction:
    Type: AWS::Serverless::Function
    Properties:
      Environment:
        Variables:
          DATABASE_URL: '{{resolve:secretsmanager:my-db-secret:SecretString:url}}'

Troubleshooting

Credentials Not Found

Unable to locate credentials

Configure AWS:

aws configure
# Or use environment variables
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
export AWS_REGION=us-east-1

S3 Bucket Access Denied

Ensure your project bucket exists:

aws s3 mb s3://my-company-deployments

Stack Update Failed

Check CloudFormation events:

aws cloudformation describe-stack-events --stack-name my-function-stack

Next Steps

• Service Configuration — Full reference
• Creating Custom Recipes — Customize the workflow
• Troubleshooting — Common issues